swiss-statistics-mcp

> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**

# 📊 swiss-statistics-mcp

![Version](https://img.shields.io/badge/version-0.6.0-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![No Auth Required](https://img.shields.io/badge/auth-none%20required-brightgreen)](https://github.com/malkreide/swiss-statistics-mcp)
![CI](https://github.com/malkreide/swiss-statistics-mcp/actions/workflows/ci.yml/badge.svg)

> MCP Server for Swiss Federal Statistical Office (BFS) data via STAT-TAB PxWeb API — 682 datasets across 21 themes, no authentication required

[🇩🇪 Deutsche Version](README.de.md)

---

### Demo

![Demo: Claude using bfs_education_stats](docs/assets/demo.svg)

---

## Maturity

This server is **Alpha (0.x)** as per the [PyPI classifier](https://pypi.org/classifiers/). Until 1.0:

- Tool names, input schemas, and output JSON keys MAY change between minor versions
- Pin cloud deployments to a specific git tag, not `main`
- Production use is acceptable for read-only Open Data scenarios; consider it experimental for anything user-facing

See [CHANGELOG.md](./CHANGELOG.md) for breaking changes.

---

## Overview

`swiss-statistics-mcp` provides AI-native access to the Swiss Federal Statistical Office (BFS) via the STAT-TAB PxWeb API, without authentication:

| Property | Details |
|----------|---------|
| **API** | STAT-TAB PxWeb API v1 |
| **Endpoint** | `https://www.pxweb.bfs.admin.ch/api/v1/` |
| **Provider** | Swiss Federal Statistical Office (BFS) |
| **Datasets** | 682 tables across 21 thematic areas |
| **Languages** | German (`de`), French (`fr`), Italian (`it`), English (`en`) |
| **Licence** | Open Government Data (OGD) — [BFS Terms of Use](https://www.bfs.admin.ch/bfs/en/home/grundlagen/nutzungsbedingungen.html) |
| **Authentication** | None — fully public |

**Anchor demo query:** *"How many students attended lower secondary schools in the canton of Zurich in 2024?"* — real BFS figures, no hallucination.

---

## Features

- 📊 **15 tools**: 8 across 21 statistical themes (682 datasets) + a 4-tool commune/historical **reference layer** + 2 construction/real-estate tools + a price-index tool
- 🔍 **Full-text search** across the entire BFS data catalogue
- 🎓 **Convenience tools** for education statistics and population data
- 🏗️ **Construction statistics** — new buildings/dwellings and building investment incl. the Arbeitsvorrat leading indicator
- 🏠 **Price indices** — construction price index (Baupreisindex, parsed series) and residential property price index (IMPI) via the BFS DAM/CKAN sources
- 🏔️ **Cross-cantonal comparison** for any table and variable
- 🔓 **No API key required** — all data under open licences
- ☁️ **Dual transport** — stdio (Claude Desktop) + Streamable HTTP (cloud)

---

## Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

---

## Installation

```bash
# Clone the repository
git clone https://github.com/malkreide/swiss-statistics-mcp.git
cd swiss-statistics-mcp

# Install
pip install -e .
# or with uv:
uv pip install -e .
```

Or with `uvx` (no permanent installation):

```bash
uvx swiss-statistics-mcp
```

---

## Quickstart

```bash
# stdio (for Claude Desktop)
python -m swiss_statistics_mcp.server

# Streamable HTTP, loopback only (default: host=127.0.0.1, port=8000)
python -m swiss_statistics_mcp.server --http --port 8000

# Streamable HTTP, all interfaces (only behind a reverse proxy with access control)
MCP_HOST=0.0.0.0 python -m swiss_statistics_mcp.server --http --port 8000
# or
python -m swiss_statistics_mcp.server --http --host 0.0.0.0 --port 8000
```

Try it immediately in Claude Desktop:

> *"How many teachers worked in the canton of Zurich in 2023?"*
> *"What is the population of canton Bern broken down by age?"*
> *"Compare the social assistance rate across all cantons for 2022."*

---

## Configuration

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "swiss-statistics": {
      "command": "python",
      "args": ["-m", "swiss_statistics_mcp.server"]
    }
  }
}
```

Or with `uvx`:

```json
{
  "mcpServers": {
    "swiss-statistics": {
      "command": "uvx",
      "args": ["swiss-statistics-mcp"]
    }
  }
}
```

**Config file locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Cursor / Windsurf / VS Code + Continue

The configuration syntax is identical to Claude Desktop. The file name depends on the client:

- **Cursor:** `.cursor/mcp.json` in the project folder, or `~/.cursor/mcp.json` globally
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
- **VS Code + Continue:** `.continue/config.json`

### Cloud Deployment (SSE for browser access)

For use via **claude.ai in the browser** (e.g. on managed workstations without local software).

> ⚠️ **Security note — this server has no authentication.** A public URL
> turns it into an open proxy to the BFS API on your deployment's IP. Any
> client with the URL can drive the tools, consume your platform quota, and
> attribute traffic to your IP. Two mitigations, in order of preference:
>
> 1. **Put it behind access control** — Render's «Private Service», Cloudflare
>    Access, or a reverse proxy with Basic-Auth / IP allowlist in front of the
>    container.
> 2. **Accept it as a public open-data proxy** — only acceptable because all
>    data is BFS OGD (Public Open Data) and tools are read-only.
>
> The server binds to `127.0.0.1` by default. To expose it on a container
> port you must explicitly set `MCP_HOST=0.0.0.0` (e.g. as a Render env var)
> or pass `--host 0.0.0.0`. Do not do this without one of the mitigations above.

**Render.com:**
1. Push/fork the repository to GitHub
2. On [render.com](https://render.com): New Web Service → connect GitHub repo
3. Set environment variable: `MCP_HOST=0.0.0.0`
4. Set start command: `python -m swiss_statistics_mcp.server --http --port 8000`
5. In claude.ai under Settings → MCP Servers, add: `https://your-app.onrender.com/sse`

> 💡 *"stdio for the developer laptop, SSE for the browser."*

---

## Output Schema

Since `v0.2.0`, every tool returns a typed Pydantic model rather than a JSON
string. FastMCP serializes these as structured content so MCP clients can
read fields directly.

```python
# Old (pre-0.2.0)
result = await bfs_get_data(...)        # str
data = json.loads(result)               # dict
print(data["rows_total"])

# New (>= 0.2.0)
result = await bfs_get_data(...)        # DataTableResult
print(result.rows_total)                # 1000
print(result.truncated)                 # True
```

Every result carries `error: str | None` and `hint: str | None` at the top
level — `result.error is None` means success. Data-returning tools
(`bfs_get_data`, `bfs_education_stats`, `bfs_population`,
`bfs_compare_cantons`) additionally expose `truncated: bool`,
`rows_total: int`, and `rows_returned: int` for machine-readable cap
detection.

| Tool | Result type |
|------|-------------|
| `bfs_browse_catalog` | `BrowseCatalogResult` |
| `bfs_search_tables` | `SearchTablesResult` |
| `bfs_get_table_metadata` | `TableMetadataResult` |
| `bfs_get_data` | `DataTableResult` |
| `bfs_education_stats` | `DataTableResult` |
| `bfs_population` | `DataTableResult` |
| `bfs_compare_cantons` | `DataTableResult` |
| `bfs_featured_datasets` | `FeaturedDatasetsResult` |
| `lookup_commune` | `LookupCommuneResult` |
| `resolve_historical_commune` | `ResolveHistoricalCommuneResult` |
| `list_communes` | `ListCommunesResult` |
| `search_historical_series` | `SearchHistoricalSeriesResult` |
| `bfs_construction_activity` | `ConstructionActivityResult` |
| `bfs_construction_investment` | `ConstructionInvestmentResult` |
| `bfs_price_index` | `PriceIndexResult` |

Reference-layer results additionally carry `source` (attribution) and `provenance` (`live_api` \| `cached`); `SearchHistoricalSeriesResult` also carries `licence_note` with the mandatory HSSO NonCommercial notice. The construction and price-index results carry `source` + `provenance` on the same envelope pattern.

---

## Available Tools

| Tool | Description |
|------|-------------|
| `bfs_featured_datasets` | Curated list of highly relevant datasets (focus on education and demographics) |
| `bfs_browse_catalog` | Browse the catalogue: all 21 themes (no `theme_code`), or all tables in a theme (e.g. `theme_code="15"` = Education and Science) |
| `bfs_search_tables` | Full-text search across the entire data catalogue (682 datasets) |
| `bfs_get_table_metadata` | Variables, values and metadata for a specific table |
| `bfs_get_data` | Data retrieval with optional filters by dimensions and values |
| `bfs_education_stats` | Convenience tool: teachers, pupils, demographic scenarios, scholarships |
| `bfs_population` | Resident population by canton, year, age structure or sex |
| `bfs_compare_cantons` | Cross-cantonal comparison for any table and any variable |
| `lookup_commune` | Resolve a commune by name or BFS number as of a given date (canton, validity, LINDAS URI) |
| `resolve_historical_commune` | Map a historical BFS number onto today's number(s) — re-key old statistics across fusions |
| `list_communes` | List all communes of a canton as of a given date |
| `search_historical_series` | Search long-run time series in Historical Statistics of Switzerland (HSSO) |
| `bfs_construction_activity` | New buildings & dwellings per commune (yearly), incl. dwelling room-size mix |
| `bfs_construction_investment` | Building investment & Arbeitsvorrat (lea