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

• 📊 9 tools across 21 statistical themes (682 datasets)
• 🔍 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.

---

Available Tools

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            │
└─────────────────┘     │                              │     └──────────────────────────┘
                        │  9 Tools                     │
                        │  682 datasets · 21 themes    │
                        │  Stdio | Streamable HTTP     │
                        │                              │
                        │  No authentication required  │
                        └──────────────────────────────┘

Data Source Characteristics

---

Project Structure

swiss-statistics-mcp/
├── src/swiss_statistics_mcp/
│   ├── __init__.py              # Package
│   └── server.py                # 9 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

---

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