Swiss Statistics MCP Server

🇨🇭 Part of the Swiss Public Data MCP Portfolio

📊 swiss-statistics-mcp

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

🇩🇪 Deutsche Version

---

Demo

---

Maturity

This server is Alpha (0.x) as per the PyPI classifier. 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 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:

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

---

Features

• 📊 13 tools: 9 across 21 statistical themes (682 datasets) + a 4-tool commune/historical reference layer
• 🔍 Full-text search across the entire BFS data catalogue
• 🎓 Convenience tools for education statistics and population data
• 🏔️ 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 (recommended) or pip

---

Installation

# 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):

uvx swiss-statistics-mcp

---

Quickstart

# 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):

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

Or with uvx:

{
  "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: 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.

# 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.

Reference-layer results additionally carry source (attribution) and provenance (live_api | cached); SearchHistoricalSeriesResult also carries licence_note with the mandatory HSSO NonCommercial notice.

---

Available Tools

The last four tools form the reference layer of the portfolio (see Join Keys): they turn official BFS commune numbers into a reliable join key and let you re-key statistics that predate a municipal merger.

Example Use Cases

→ More use cases by audience →

---

Themes

---

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────────────────┐
│   Claude / AI   │────▶│  Swiss Statistics MCP          │────▶│  BFS STAT-TAB            │
│   (MCP Host)    │◀────│  (MCP Server)                │◀────│  PxWeb API v1            │
└─────────────────┘     │                              │     └──────────────────────────┘
                        │  13 Tools                    │
                        │  + commune & historical ref  │
                        │  Stdio | Streamable HTTP     │
                        │                              │
                        │  No authentication required  │
                        └──────────────────────────────┘

Data Source Characteristics

Architecture decision

• AGVCH commune register → Architecture A (live-API-only). The official REST service (snapshot / correspondances / mutations / levels) is a clean, versioned, no-auth API — verified live on 2026-07-19 — so the commune tools query it directly with a 24 h in-memory cache and the shared retry policy. No dump fallback is needed. Finding: the live snapshot CSV header uses Inscription,Radiation,Rec_Type_fr (not the Einschreibung,Streichung names printed in the API PDF), and HistoricalCode is not globally unique across levels — the Parent link is disambiguated by tier when deriving a commune's canton.
• HSSO → Architecture C (dump-only). HSSO offers no API, only static per-table XLSX at stable URLs (/get/{CHAPTER}.{NN}{suffix}.xlsx). search_historical_series builds a cached title index from the chapter pages and returns the stable download URL. HSSO is licensed CC BY-NC-SA 3.0 (NonCommercial) — different from this server's OGD baseline — so every HSSO response carries an explicit NonCommercial notice in licence_note.

---

Join Keys

The reference layer exists so that data from different servers in the Swiss Public Data MCP Portfolio can be joined reliably. Three identifiers are the portfolio-wide keys:

Why re-keying matters. BFS commune numbers change whenever communes merge, split, or move canton. Statistics published before a merger use the old number; joining them to today's data without re-keying silently drops or misattributes rows. resolve_historical_commune(bfs_number, from_date, to_date) returns the resolves_to set — the current number(s) old figures must be aggregated onto — plus the mutation_path (the fusions/renamings, with dates). Other portfolio servers are meant to mirror this contract conceptually so the same key resolves the same way everywhere.

Example (anchor query). "Which Zurich communes have merged since 2000?" — e.g. old 132 Hirzel and 133 Horgen both re-key onto today's 295 Horgen; 134/140/142 onto 293 Wädenswil.

---

Project Structure

swiss-statistics-mcp/
├── src/swiss_statistics_mcp/
│   ├── __init__.py              # Package
│   └── server.py                # 13 tools
├── tests/
│   └── test_server.py           # Unit + integration tests (mocked HTTP)
├── .github/workflows/ci.yml     # GitHub Actions (Python 3.11/3.12/3.13)
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md              # English
├── CONTRIBUTING.de.md           # German version
├── SECURITY.md                  # English
├── SECURITY.de.md               # German version
├── LICENSE
├── README.md                    # This file (English)
└── README.de.md                 # German version

---

Observability

The server emits one JSON log line per tool call on stderr:

{"ts": "2026-05-20T04:02:28", "level": "INFO", "logger": "swiss_statistics_mcp",
 "event": "tool_start", "tool": "bfs_list_themes", "rid": "1091cb73", "params_keys": ["lang"]}
{"ts": "2026-05-20T04:02:28", "level": "INFO", "logger": "swiss_statistics_mcp",
 "event": "tool_end", "tool": "bfs_list_themes", "rid": "1091cb73", "status": "ok", "duration_ms": 303}

• rid — 8-char correlation id linking tool_start and tool_end for the same call
• params_keys — sorted list of input field names (no values, no PII)
• duration_ms — per-call latency on the tool_end event
• status — "ok" or "error"; error_type is added when a tool raises

Render and other cloud platforms can index these directly for per-tool latency dashboards and error-rate alerts. Set MCP_LOG_LEVEL=DEBUG for verbose output or WARNING to suppress per-call events.

ℹ️ Logs go to stderr so they never collide with the MCP protocol on stdio transport (which uses stdout).

---

Resilience

The server absorbs transient BFS-API hiccups before they reach the LLM:

• Retries — 5xx, 429, and network errors are retried up to 3 times with exponential backoff (0.5s → 4s). 4xx errors surface immediately so client bugs aren't masked. Tunable via MCP_RETRY_MAX_ATTEMPTS, MCP_RETRY_WAIT_INITIAL, MCP_RETRY_WAIT_MAX env vars.
• Metadata cache — Table metadata (variables, value domains, last_updated) is cached in-memory per (table_id, lang) for 1h. Cold list/detail flows warm the cache; subsequent calls return instantly.
• Concurrency cap — Fan-out metadata fetches in bfs_list_tables_by_theme run in parallel bounded by FANOUT_CONCURRENCY = 5. For limit=20 this cuts wall-clock from ~20s sequential to ~4s, without overwhelming the upstream API.

---

Known Limitations

• PxWeb API: Rate limiting may apply for rapid successive queries; the server uses a 1-hour cache for the catalogue index and a 1-hour cache for table metadata
• Language: Dataset titles and dimension values are in German by default; French, Italian and English coverage varies by table
• JSON-STAT2: Some complex cross-tabulations may return large result sets; use dimension filters to narrow queries
• Commune register (AGVCH): Live snapshot CSV headers use Inscription/Radiation/Rec_Type_fr (not the Einschreibung/Streichung names in the API PDF); HistoricalCode is not globally unique across levels, so the canton is derived by walking the Parent chain one tier at a time. Snapshots/mutations are cached for 24 h.
• HSSO: Licensed CC BY-NC-SA 3.0 (NonCommercial) — attribution required, no commercial use; every response carries this in licence_note. HSSO exposes no per-table period filter, so search_historical_series's period argument is an informational hint only — verify the actual span in the XLSX. search_historical_series returns the stable XLSX download URL, not the parsed series values.

---

Testing

# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (live API calls)
pytest tests/ -m "live"

---

Safety & Limits

• Read-only: All tools perform HTTP GET requests only — no data is written, modified, or deleted.
• No personal data: STAT-TAB returns aggregated statistical datasets. No personally identifiable information (PII) is processed or stored by this server.
• Rate limits: The PxWeb API is a public endpoint without documented rate limits; avoid tight loops over the full 682-table catalogue. The server enforces a 30s timeout per request and caches the catalogue index for 1 hour.
• Data freshness: BFS publishes updated figures periodically (not real-time). Figures reflect the state of the upstream database at query time.
• Terms of service: Data is subject to the BFS Terms of Use (OGD). All STAT-TAB data is published as Open Government Data and may be freely used with attribution.
• No guarantees: This server is a community project, not affiliated with the Swiss Federal Statistical Office. Availability depends on the upstream BFS API.

---

Changelog

See CHANGELOG.md

---

Contributing

See CONTRIBUTING.md

---

Security

Read-only, no PII, no authentication, single fixed BFS endpoint. See SECURITY.md for the full security posture and accepted-risk decisions.

---

License

MIT License — see LICENSE

---

Author

Hayal Oezkan · malkreide

---

Credits & Related Projects

• BFS: www.bfs.admin.ch — Swiss Federal Statistical Office
• STAT-TAB: www.pxweb.bfs.admin.ch — PxWeb database interface
• Protocol: Model Context Protocol — Anthropic / Linux Foundation
• Related: swiss-cultural-heritage-mcp — SIK-ISEA, Nationalmuseum, Nationalbibliothek
• Related: fedlex-mcp — Swiss federal law via Fedlex SPARQL
• Related: zurich-opendata-mcp — CKAN, weather, air quality, City of Zurich
• Related: swiss-transport-mcp — OJP journey planning, SIRI-SX disruptions
• Related: global-education-mcp — UNESCO UIS and OECD Education at a Glance
• Portfolio: Swiss Public Data MCP Portfolio

Installation

Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

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