swiss-statistics-mcp
Advanced tools
MCP Server for Swiss Federal Statistical Office (BFS) data via STAT-TAB PxWeb API
🇨🇭 Part of the Swiss Public Data MCP Portfolio
MCP Server for Swiss Federal Statistical Office (BFS) data via STAT-TAB PxWeb API — 682 datasets across 21 themes, no authentication required
This server is Alpha (0.x) as per the PyPI classifier. Until 1.0:
mainSee CHANGELOG.md for breaking changes.
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 |
| 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.
# 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
# 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."
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:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonThe configuration syntax is identical to Claude Desktop. The file name depends on the client:
.cursor/mcp.json in the project folder, or ~/.cursor/mcp.json globally~/.codeium/windsurf/mcp_config.json.continue/config.jsonFor 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:
- 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.
- 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.1by default. To expose it on a container port you must explicitly setMCP_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:
MCP_HOST=0.0.0.0python -m swiss_statistics_mcp.server --http --port 8000https://your-app.onrender.com/sse💡 "stdio for the developer laptop, SSE for the browser."
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.
| 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.
| 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 (leading indicator) by region/canton/commune |
bfs_price_index | Construction price index (Baupreisindex, parsed series) / residential property price index (IMPI, source links) |
Four of these 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. The two bfs_construction_* tools cover STAT-TAB theme 09 (Bau- und Wohnungswesen) — see Construction sources. bfs_price_index covers price indices that are not in STAT-TAB — see Price-index sources.
| Cube ID | Title | Coverage | Used by |
|---|---|---|---|
px-x-0904030000_106 | Neu erstellte Gebäude mit Wohnungen nach Gemeinde, Gebäudetyp | 2013– | bfs_construction_activity |
px-x-0904030000_105 | Neu erstellte Wohnungen nach Gemeinde, Anzahl Zimmer | 2013– | bfs_construction_activity |
px-x-0904010000_205 | Bauinvestitionen und Arbeitsvorrat nach Grossregion/Kanton/Gemeinde | 1994– | bfs_construction_investment |
The pre-2013 Gemeinde-level building series lives in the discontinued cubes
px-x-0904030000_101/_104(1995–2012), which use a different geo coding and are not queried by these tools. Building/dwelling figures are the consolidated official yearly statistics — for up-to-date register states and the construction pipeline, cross-validate againstswiss-housing-mcp(deliberate redundancy).
bfs_price_index covers two indices that are not published via STAT-TAB. Their datasets live on opendata.swiss (CKAN); the data files themselves are BFS DAM assets.
| Index | Source | Returns |
|---|---|---|
baupreisindex | opendata.swiss dataset Schweizerischer Baupreisindex (Multibasen) → DAM XLSX asset | Parsed national semi-annual index series (Schweiz, Baugewerbe Total), with the base period |
impi | opendata.swiss dataset Schweizerischer Wohnimmobilienpreisindex (IMPI) → DAM PDF/HTML assets | Official source links only — BFS does not publish a machine-readable IMPI series |
Two quirks are handled for you:
ckan.opendata.swissreturns HTTP 403 to default User-Agents, so every call sends a customswiss-statistics-mcp/<version>User-Agent; and DAM assets mix formats, so the XLSX is selected by verifying the responsecontent-type(PDFs are skipped). Results are cached for 24 h.
| Query | Tool |
|---|---|
| "How many teachers worked in Zurich in 2023?" | bfs_education_stats |
| "How will upper secondary enrolment develop until 2031?" | bfs_education_stats |
| "What is the population of canton Zurich by age?" | bfs_population |
| "Compare the social assistance rate across all cantons" | bfs_compare_cantons |
| "Is there data on school buildings?" | bfs_search_tables |
| "Which Zurich communes have merged since 2000, and onto which of today's BFS numbers must I re-key old statistics?" | resolve_historical_commune |
| "List all communes of canton Glarus today" | list_communes |
| "Find long-run series on population in HSSO" | search_historical_series |
| "How many new dwellings were built in Winterthur since 2018, by room size?" | bfs_construction_activity |
| "What is the building investment and Arbeitsvorrat for canton Zurich?" | bfs_construction_investment |
| "How has the construction price index moved since 2015?" | bfs_price_index |
→ More use cases by audience →
| Code | Theme | Code | Theme |
|---|---|---|---|
| 01 | Population | 12 | Money, banks, insurance |
| 02 | Territory and environment | 13 | Social security |
| 03 | Work and income | 14 | Health |
| 04 | National economy | 15 | Education and science |
| 05 | Prices | 16 | Culture, media, information society |
| 06 | Industry and services | 17 | Politics |
| 07 | Agriculture and forestry | 18 | General government |
| 08 | Energy | 19 | Crime and criminal justice |
| 09 | Construction and housing | 20 | Economic and social situation |
| 10 | Tourism | 21 | Sustainable development |
| 11 | Mobility and transport |
┌─────────────────┐ ┌──────────────────────────────┐ ┌──────────────────────────┐
│ Claude / AI │────▶│ Swiss Statistics MCP │────▶│ BFS STAT-TAB │
│ (MCP Host) │◀────│ (MCP Server) │◀────│ PxWeb API v1 │
└─────────────────┘ │ │ └──────────────────────────┘
│ 15 Tools │
│ + commune/historical ref │
│ + construction (theme 09) │
│ + price indices (DAM/CKAN) │
│ Stdio | Streamable HTTP │
│ │
│ No authentication required │
└──────────────────────────────┘
| Source | Protocol | Coverage | Auth | Licence |
|---|---|---|---|---|
| BFS STAT-TAB | PxWeb REST API | 682 tables, 21 themes | None | OGD |
| BFS AGVCH (commune register) | REST (CSV/XLSX) | Snapshots, mutations, correspondances | None | OGD |
| HSSO (historical statistics) | Static XLSX dumps | ~750 long-run tables | None | CC BY-NC-SA 3.0 |
| BFS DAM + opendata.swiss (CKAN) | CKAN metadata + DAM XLSX/PDF | Baupreisindex, IMPI | None (custom UA required) | OGD |
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./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.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:
| Key | What it identifies | Canonical form | Notes |
|---|---|---|---|
BFS commune number (BfsCode) | A political commune | integer, e.g. 261 (Zürich) | The primary join key across statistics, geo, education and health data. Stable LINDAS/Linked-Data URI: https://ld.admin.ch/municipality/{BfsCode}. Not stable over time — a merger issues a new number, so historical data must be re-keyed via resolve_historical_commune. |
| EGID | A single building (Eidg. Gebäudeidentifikator) | 9-digit integer | The join key for building/dwelling-level data (GWR, energy, addresses). A commune contains many EGIDs; BfsCode is the commune each EGID sits in. |
| Canton abbreviation | A canton | two letters, e.g. ZH | The coarsest geographic key. Derivable from any commune via its Parent chain (exposed as canton_abbr). |
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.
swiss-statistics-mcp/
├── src/swiss_statistics_mcp/
│ ├── __init__.py # Package
│ └── server.py # 15 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
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_browse_catalog", "rid": "1091cb73", "params_keys": ["theme_code", "lang", "limit"]}
{"ts": "2026-05-20T04:02:28", "level": "INFO", "logger": "swiss_statistics_mcp",
"event": "tool_end", "tool": "bfs_browse_catalog", "rid": "1091cb73", "status": "ok", "duration_ms": 303}
rid — 8-char correlation id linking tool_start and tool_end for the same callparams_keys — sorted list of input field names (no values, no PII)duration_ms — per-call latency on the tool_end eventstatus — "ok" or "error"; error_type is added when a tool raisesRender 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).
The server absorbs transient BFS-API hiccups before they reach the LLM:
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.(table_id, lang) for 1h. Cold list/detail flows
warm the cache; subsequent calls return instantly.bfs_browse_catalog
(theme mode) 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.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.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.px-x-0904030000_106/_107 the value code IS the zero-padded BFS number (0261); in px-x-0904030000_105 it is an opaque sequential id (160) and the BFS number appears only in the label (......0261 Zürich). bfs_construction_activity resolves each cube against its own live dimension values by matching the label-embedded BFS number, never by guessing the code.bfs_construction_activity therefore accepts since_year >= 2013. Values are the consolidated official yearly statistics. Building investment values (bfs_construction_investment) are in 1000 CHF; the Arbeitsvorrat is the following year's building volume (a monetary leading indicator).bfs_price_index): the IMPI (residential property price index) is published by BFS only as PDF/HTML — there is no machine-readable series — so index="impi" returns the official source links plus an explicit limitation, not values. The Baupreisindex XLSX is parsed to the national semi-annual series (Schweiz, Baugewerbe Total); regional/object-type breakdowns exist in the source XLSX but are not returned. The DAM asset ids are resolved live from CKAN metadata (never hard-coded), because they change on republish; if the upstream XLSX structure changes, the tool degrades to a clear error rather than returning wrong values.# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"
# Integration tests (live API calls)
pytest tests/ -m "live"
See CHANGELOG.md
See CONTRIBUTING.md
Read-only, no PII, no authentication, single fixed BFS endpoint. See SECURITY.md for the full security posture and accepted-risk decisions.
MIT License — see LICENSE
Hayal Oezkan · malkreide
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"
]
}
}
}
FAQs
MCP Server for Swiss Federal Statistical Office (BFS) data via STAT-TAB PxWeb API
The pypi package swiss-statistics-mcp receives a total of 122 weekly downloads. As such, swiss-statistics-mcp popularity was classified as not popular.
We found that swiss-statistics-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.