🇨🇭 Part of the Swiss Public Data MCP Portfolio

🗺️ swisstopo-mcp

MCP server for Swiss federal geodata -- maps, elevation, geocoding, cadastral extracts, and downloadable datasets via Swisstopo APIs

🇩🇪 Deutsche Version

Overview

swisstopo-mcp gives AI assistants access to Switzerland's official geodata infrastructure through 24 tools, all without authentication:

Source	Data	API
Swisstopo REST API	500+ geodata layers (buildings, boundaries, land use)	REST/JSON
Geocoding	Official addresses, place names, postal codes	REST/JSON
Height Service	Elevation above sea level, elevation profiles	REST/JSON
STAC Catalog	Orthophotos, elevation models, 3D buildings	STAC 0.9
WMTS	National maps, aerial images, zoning maps	URL builder
OEREB Cadastre	Public-law restrictions, parcels	REST/JSON (cantonal)
geodienste.ch	Interkantonale Basisgeodaten (cadastral survey, contaminated sites, hazard maps, …)	OGC API Features / WMS / WFS
OpenStreetMap	Points of interest (schools, playgrounds, pharmacies, …)	Overpass API (ODbL)
OpenPLZ API	Administrative address level: postal codes → commune (BFS number) → district → canton	REST/JSON (BFS + swisstopo OGD)

Anchor demo query: "Which communes are in the Uster district, and what are their BFS numbers for joining with BFS statistics data?" (The BFS commune number is the official join key to swiss-statistics-mcp and zurich-opendata-mcp — this is what turns a geodata wrapper into a semantic connector at the commune level.) → More use cases by audience →

Demo

Demo: Claude using swisstopo_find_commune and swisstopo_lookup_postal_code

Features

🗺️ 24 tools (REST, Geocoding, Height, STAC, WMTS, OEREB, geodienste.ch, OpenStreetMap/Overpass, OpenPLZ)
🏛️ Resolve the administrative address level (PLZ → commune/BFS number → district → canton) via OpenPLZ
🔍 Geocode Swiss addresses and reverse-geocode coordinates
🏔️ Query elevation and compute elevation profiles
📦 Discover and download geodatasets (orthophotos, 3D buildings, historical maps)
🏗️ Identify map features at coordinates across 500+ Swisstopo layers
🔗 Generate shareable map.geo.admin.ch links
📋 Look up cadastral property IDs (EGRID) and retrieve OEREB extracts
🔓 No API key required for all tools (OEREB extract needs a supported canton)
☁️ 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/swisstopo-mcp.git
cd swisstopo-mcp

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

Or with uvx (no permanent installation):

uvx swisstopo-mcp

Quickstart

# stdio (for Claude Desktop)
python -m swisstopo_mcp.server

# Streamable HTTP (port 8000)
python -m swisstopo_mcp.server --http --port 8000

Try it immediately in Claude Desktop:

"Where is Bahnhofstrasse 1, Zurich? Give me the coordinates." "What is the elevation at the Uetliberg summit?" "What buildings are at coordinates 2683500, 1247500 (LV95)?"

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "swisstopo": {
      "command": "python",
      "args": ["-m", "swisstopo_mcp.server"]
    }
  }
}

Or with uvx:

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

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Cloud Deployment (SSE for browser access)

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

Render.com (recommended):

Push/fork the repository to GitHub
On render.com: New Web Service -> connect GitHub repo
Set start command: python -m swisstopo_mcp.server --http --port 8000
In claude.ai under Settings -> MCP Servers, add: https://your-app.onrender.com/sse

Available Tools

REST API (Layer & Feature Queries)

Tool	Description
`swisstopo_search_layers`	Search the Swisstopo layer catalog (500+ layers) by keyword
`swisstopo_identify_features`	Find map features at a specific coordinate (spatial query)
`swisstopo_find_features`	Search features by attribute value within a layer (e.g. buildings by EGID)
`swisstopo_get_feature`	Retrieve full attributes and geometry for a feature by ID
`swisstopo_layer_info`	List a layer's queryable fields and its legend (which `search_field` values are valid)
`swisstopo_zoning_at`	Harmonised building zone at a coordinate — one call, no layer lookup (not legally binding)
`swisstopo_municipality_at`	Municipality, canton and official BFS number at a coordinate

Geocoding

Tool	Description
`swisstopo_geocode`	Convert Swiss addresses, place names, or postal codes to coordinates
`swisstopo_reverse_geocode`	Find the nearest address for given coordinates

Height Service

Tool	Description
`swisstopo_get_height`	Get elevation above sea level (m a.s.l.) at a coordinate
`swisstopo_elevation_profile`	Compute an elevation profile along a line
`swisstopo_convert_coordinates`	Official WGS84 ↔ LV95 conversion via the swisstopo REFRAME service

STAC Catalog (Geodata Downloads)

Tool	Description
`swisstopo_search_geodata`	Search the STAC catalog for downloadable geodatasets
`swisstopo_get_collection`	Get details and download links for a STAC collection

WMTS (Map URLs)

Tool	Description
`swisstopo_map_url`	Generate a map.geo.admin.ch URL for browser display

OEREB Cadastre

Tool	Description
`swisstopo_get_egrid`	Resolve a cadastral property ID (EGRID) from coordinates
`swisstopo_get_oereb_extract`	Retrieve public-law land-use restrictions (OEREB) for a parcel

Consolidated Geodata Façade

One façade over several map/layer sources, kept under the 25-tool budget (see docs/geodaten-erweiterung-phase1.md):

Tool	Description
`swisstopo_list_available_layers`	Discover layer keys for `swisstopo_query_geodata` (`strassenverzeichnis`, `oereb-verfuegbarkeit`, `geodienste:<topic>:<canton>`); filters to contract-free geodienste datasets
`swisstopo_query_geodata`	Query a chosen layer by `point` / `bbox` / `commune` — amtliches Strassenverzeichnis, interkantonale geodienste.ch data (OGC API Features), or ÖREB availability
`swisstopo_query_osm_features`	OpenStreetMap POIs (schools, playgrounds, pharmacies, …) around a point via Overpass — separate source, ODbL (© OpenStreetMap contributors)

Administrative Address Level (OpenPLZ)

The amtliche address hierarchy PLZ → commune → district → canton, served by the OpenPLZ API (data: BFS municipal directory + swisstopo street directory, Swiss OGD — a separate source and licence from the swisstopo geodata above). Every commune-bearing response exposes bfs_commune_number as a named top-level field: the official join key to BFS statistics (swiss-statistics-mcp) and zurich-opendata-mcp.

Tool	Description
`swisstopo_lookup_postal_code`	Resolve a Swiss postal code → locality, commune (+BFS number), district, canton
`swisstopo_find_commune`	Resolve a commune both directions (`name` ↔ `bfs_number`) or list all communes of a `canton` / `district`. Accepts canton abbreviation (`ZH`) or key (`1`); resolution happens server-side
`swisstopo_search_address`	Full-text search over Swiss streets and localities, returning commune + BFS number per hit

Example Use Cases

Query	Tool
"Where is Bahnhofstrasse 1, Zurich?"	`swisstopo_geocode`
"What is the elevation at the Uetliberg summit?"	`swisstopo_get_height`
"What buildings are at coordinates 2683500, 1247500?"	`swisstopo_identify_features`
"Find orthophoto datasets for download"	`swisstopo_search_geodata`
"Show me a map of Bern at zoom level 10"	`swisstopo_map_url`
"What restrictions apply to parcel at Musterstrasse 5?"	`swisstopo_get_egrid` + `swisstopo_get_oereb_extract`
"Which schools are within 500 m of Bederstrasse 109, 8002 Zürich, and which streets lead there?"	`swisstopo_query_osm_features` + `swisstopo_query_geodata` (`strassenverzeichnis`)
"Which contaminated-sites data is free for canton ZH?"	`swisstopo_list_available_layers` + `swisstopo_query_geodata` (`geodienste:kataster_belasteter_standorte:ZH`)
"Which communes are in the Uster district and what are their BFS numbers?"	`swisstopo_find_commune` (`district=109`)
"Which commune and canton does postal code 8001 belong to?"	`swisstopo_lookup_postal_code`
"What is the BFS number of Winterthur (to join with BFS statistics)?"	`swisstopo_find_commune` (`name=Winterthur`)

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────────────────┐
│   Claude / AI   │────▶│  swisstopo-mcp               │────▶│  Swisstopo REST API      │
│   (MCP Host)    │◀────│  (MCP Server)                │◀────│  api3.geo.admin.ch       │
└─────────────────┘     │                              │     ├──────────────────────────┤
                        │  24 Tools                    │────▶│  Geocoding               │
                        │  Stdio | Streamable HTTP     │◀────│  api3.geo.admin.ch       │
                        │                              │     ├──────────────────────────┤
                        │  No authentication required  │────▶│  STAC Catalog            │
                        │  (all tools; OEREB canton opt) │◀────│  data.geo.admin.ch       │
                        │                              │     ├──────────────────────────┤
                        │                              │────▶│  OEREB Cadastre          │
                        │                              │◀────│  (cantonal endpoints)    │
                        │                              │     ├──────────────────────────┤
                        │                              │────▶│  geodienste.ch (OGC API) │
                        │                              │◀────│  overpass.osm.ch (ODbL)  │
                        │                              │     ├──────────────────────────┤
                        │  BFS-Nr = join key to        │────▶│  OpenPLZ API             │
                        │  swiss-statistics-mcp        │◀────│  openplzapi.org (BFS/OGD)│
                        └──────────────────────────────┘     └──────────────────────────┘

Project Structure

swisstopo-mcp/
├── src/swisstopo_mcp/
│   ├── __init__.py              # Package version
│   ├── server.py                # MCP server wiring (tool registrations)
│   ├── api_client.py            # Shared HTTP client (httpx + error handling)
│   ├── geocoding.py             # swisstopo_geocode, swisstopo_reverse_geocode
│   ├── rest_api.py              # swisstopo_search_layers, identify, find, get_feature
│   ├── height.py                # swisstopo_get_height, swisstopo_elevation_profile
│   ├── stac.py                  # swisstopo_search_geodata, swisstopo_get_collection
│   ├── wmts.py                  # swisstopo_map_url
│   ├── oereb.py                 # swisstopo_get_egrid, swisstopo_get_oereb_extract
│   ├── geodata.py               # swisstopo_query_geodata + swisstopo_list_available_layers (façade)
│   ├── overpass.py              # swisstopo_query_osm_features (OpenStreetMap / Overpass)
│   └── openplz.py               # swisstopo_lookup_postal_code, swisstopo_find_commune, swisstopo_search_address (OpenPLZ)
├── tests/
│   ├── test_api_client.py
│   ├── test_geocoding.py
│   ├── test_height.py
│   ├── test_oereb.py
│   ├── test_rest_api.py
│   ├── test_stac.py
│   ├── test_wmts.py
│   ├── test_geodata.py
│   ├── test_overpass.py
│   ├── test_openplz.py
│   └── test_retry.py
├── .github/workflows/ci.yml     # GitHub Actions (Python 3.11/3.12/3.13)
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md               # Contribution guide (English)
├── CONTRIBUTING.de.md            # Contribution guide (German)
├── SECURITY.md                   # Security policy (English)
├── SECURITY.de.md                # Security policy (German)
├── LICENSE
├── README.md                    # This file (English)
└── README.de.md                 # German version

Security & Compliance

The full security policy and posture is documented in SECURITY.md.

Phase

This server is in Phase 2.5 — Consolidation of swiss-geodata-mcp (see docs/roadmap.md, the single authority for phase state).

Property	Status
Read tools	23, all `readOnlyHint: true` / `destructiveHint: false`
Write tools	none — Phase 3, not planned
Transport	stdio (default) and Streamable-HTTP
Last audit	`audits/2026-07-27T125314-Z-swisstopo-mcp/`

A phase advance requires: the phase's roadmap items checked off, a re-run audit with no open critical findings, and a CHANGELOG entry naming the new phase. Phase 3 (write tools) additionally requires re-running the Lethal-Trifecta assessment and a security review before any implementation starts.

Tool budget and aggregation

24 tools against a self-imposed budget of 25. The check's ideal is ≤12, so the count needs an argument, not just a number. Per cluster:

The five api3 tools (search_layers, layer_info, identify_features, find_features, get_feature) are kept separate because their argument shapes are genuinely disjoint: a geometry, an attribute name plus value, and an opaque feature ID. Merging them behind one tool with a discriminated union would turn a tool choice into a variant choice — the same decision, relocated, plus a schema the caller must navigate. The audit notes the real risk here: a wrong pick returns empty rather than erroring. That is mitigated instead by the note hints added for ARCH-003, which name the likely mistake and the tool to use. This remains a merge candidate for a future major release, not a settled question.

Search → detail pairs. search_geodata → get_collection is a genuine pair: STAC collection metadata is large and callers usually want one of many search hits. get_egrid → get_oereb_extract was the same shape and has been collapsed: swisstopo_oereb_at answers the actual question in one call and resolves the EGRID internally, because the EGRID is an upstream identifier rather than something a caller asked for. get_egrid remains for callers who want the parcel ID itself.

Genuine aggregation already in place. query_geodata fronts three sources behind one tool; zoning_at and municipality_at each collapse a discovery chain that previously took two calls.

When the next source is added, the choice is a raise or a consolidation. The consolidation on the table is the api3 five; it is a breaking change and should ride a major release together with any other renames.

Data sources and licences

Every response carries source and license. ARE is a different federal office from swisstopo, so its licence is asserted rather than inherited.

Source	Served by	Licence
swisstopo / geo.admin.ch	most tools	Swiss OGD (opendata.swiss)
swisstopo REFRAME (geodesy.geo.admin.ch)	`swisstopo_convert_coordinates`	Swiss OGD (opendata.swiss)
swissBOUNDARIES3D (swisstopo)	`swisstopo_municipality_at`	Swiss OGD (opendata.swiss)
`ch.are.bauzonen` (ARE)	`swisstopo_zoning_at`	Swiss OGD — Bundesamt für Raumentwicklung ARE
Cantonal ÖREB cadastre	`swisstopo_get_egrid`, `swisstopo_get_oereb_extract`	Cantonal ÖREB terms
geodienste.ch (cantons)	`swisstopo_query_geodata`	Free use — attribution required
OpenStreetMap (Overpass)	`swisstopo_query_osm_features`	ODbL — © OpenStreetMap contributors
OpenPLZ (BFS + swisstopo)	`swisstopo_lookup_postal_code`, `swisstopo_find_commune`, `swisstopo_search_address`	Free use — attribution required

ch.are.bauzonen is a federal synthesis for cross-cantonal comparability and is not legally binding — only the cantonal or communal Nutzungsplanung is. That caveat is carried on every swisstopo_zoning_at result record.

Project structure

The tool modules sit flat under src/swisstopo_mcp/ rather than in a tools/ sub-package. Each module maps to exactly one upstream API family — rest_api.py → api3 MapServer, stac.py → STAC, oereb.py → cantonal ÖREB, openplz.py → OpenPLZ, overpass.py → OSM, coords.py → REFRAME — which is the axis along which this server's code actually varies. A tools/ level would add a directory without adding a distinction.

server.py contains tool registrations only; every tool body lives in its domain module. Splitting it further is a readability question, not a structural one.

Lethal Trifecta assessment

Capability	Status	Rationale
Access to private data	❌ No	Public Open Data only (federal/cantonal geodata)
Exposure to untrusted content	⚠️ Limited	Reads only from a fixed allow-list of trusted geo.admin / OEREB hosts
External communication (write/send)	❌ No	Read-only; no mail/webhook/write tools

Trifecta score: at most 1 of 3 — safe by design.

Egress

Outbound requests are restricted to an explicit code-layer allow-list and redirects are disabled — see docs/network-egress.md.

Container deployment

For containerised HTTP deployments, a hardened Dockerfile and Kubernetes manifests (non-root, read-only root filesystem, dropped capabilities, egress NetworkPolicy) are provided — see docs/deployment.md.

MCP Protocol Version

The MCP protocol version is negotiated during initialize; the Python SDK does not expose an author-settable pin. As of mcp 1.28.1 the negotiated version is 2025-11-25 (mcp.types.LATEST_PROTOCOL_VERSION). The SDK is pinned to the 1.x major in pyproject.toml so an update cannot silently move it, and tests/test_protocol_version.py fails if it does — a Dependabot bump cannot change the protocol version unnoticed.

Update policy

SDK updates are tested on a feature branch before merge.
A change to the negotiated protocol version is recorded in CHANGELOG.md under ### Changed, naming the old and the new version.
A protocol change that breaks existing clients triggers a major release.

Sessions & Authentication

The server is unauthenticated by design — it serves only public open data. Over HTTP, session IDs are managed entirely by the FastMCP framework; there is no per-user state, so there is nothing user-specific to bind a session to. If an authenticated deployment is ever introduced, session IDs must be bound to the validated user identity (audit finding SEC-009).

Error handling

Execution errors (upstream failure, invalid value) are returned as a ToolResponse with is_error: true and a user-friendly summary; raw exception text is never leaked to the client (it is logged to stderr instead).
Protocol errors (unknown tool, malformed/invalid arguments) are emitted by the MCP SDK as JSON-RPC errors with standard codes (e.g. -32602 invalid params). Input validation happens at the Pydantic boundary (SEC-018).

MCP Primitives

This server intentionally exposes Tools only (no Resources or Prompts): it is a Phase-1 read-only wrapper, and every result is a live, parameterised API query rather than a static addressable document. Resources/Prompts may be added in a later phase if stable URI schemes emerge.

Tool workflows

Most tools return a thought-complete result in a single call. Two domains use a short, documented discovery chain (each tool's description states the next step):

Feature query: swisstopo_search_layers (find layer IDs) → swisstopo_identify_features / swisstopo_find_features → swisstopo_get_feature (full detail).
Cadastre: swisstopo_geocode → swisstopo_get_egrid → swisstopo_get_oereb_extract.
Downloads: swisstopo_search_geodata → swisstopo_get_collection.

Response Format

Every tool returns a structured ToolResponse (FastMCP emits it as structured content with an output schema, plus a JSON text block):

Field	Meaning
`summary`	Human-readable Markdown summary
`results`	Machine-readable structured records
`count`	Number of `results`
`match_type`	`exact` / `fuzzy` / `none` (search-style tools)
`source` / `license`	Data attribution (OGD-CH, CC/OGD terms)
`provenance` / `retrieved_at`	How and when the data was obtained
`is_error`	`true` for handled errors

Known Limitations

OEREB tools require a canton parameter; not all cantons expose the same API format
STAC catalog uses Swisstopo's v0.9 endpoint; some collections may lack complete metadata
Geocoding covers Swiss addresses only (no Liechtenstein)
Rate limits are enforced by Swisstopo; high-frequency usage may be throttled

Known findings — OpenPLZ live probe (2026-07-20)

The OpenPLZ endpoints were probed live before implementation. Findings baked into the tools:

Endpoint / behaviour	Result	Handling
`/Cantons`	200, 26 records, `key` = BFS canton number (ZH = `1`)	canton abbreviation resolved from this list
`/Cantons/{key}/Districts\|Communes`	200	path param is the numeric key
`/Cantons/ZH/Districts` (abbreviation)	200 + `[]` — not an error	`ZH`→`1` resolved server-side; empty answer gets an explanatory note
`/Localities?postalCode=8001`	200, `commune.key = 261` (BFS Zürich)	`bfs_commune_number` surfaced top-level
`/Localities?postalCode=9999` (unknown)	200 + `[]`	reported as a note — empty ≠ absent
list endpoints pagination	default `pageSize=10`, hard max 50 (`100` → HTTP 400)	tools iterate pages via `x-total-count`
raw umlaut in query (`?name=Zürich`)	HTTP 400	httpx URL-encodes params automatically
`historicalCode` field	≠ `key` for communes (historized-directory id)	not used; the join key is the current `key`
bulk dump	none from OpenPLZ (only `/swagger`)	Architecture A (live-API-only) — adequate for a lookup connector

The abbreviation-vs-key trap in one line: an empty OpenPLZ list is almost never proof that something does not exist — it usually means a wrong path parameter (an abbreviation where a numeric key was expected). The tools resolve abbreviations server-side and annotate every empty result.

Testing

# Unit tests (no network required)
pytest tests/ -m "not live"

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

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

Security

Read-only, no authentication, public geodata only. See SECURITY.md (Deutsch) for the security posture and how to report a vulnerability.

License

MIT License -- see LICENSE

Data provided by swisstopo under Open Government Data terms.

Author

Hayal Oezkan · malkreide

Credits & Related Projects

Swisstopo: www.swisstopo.admin.ch -- Swiss Federal Office of Topography
Swisstopo APIs: api3.geo.admin.ch / data.geo.admin.ch
Protocol: Model Context Protocol -- Anthropic / Linux Foundation
Related: zurich-opendata-mcp -- Zurich city open data
Related: swiss-transport-mcp -- Swiss public transport
Related: swiss-cultural-heritage-mcp -- Swiss cultural heritage
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": {
    "swisstopo-mcp": {
      "command": "uvx",
      "args": [
        "swisstopo-mcp"
      ]
    }
  }
}

Swisstopo MCP

At a glance

README

🗺️ swisstopo-mcp

Overview

Demo

Features

Prerequisites

Installation

Quickstart

Configuration

Claude Desktop

Cloud Deployment (SSE for browser access)

Available Tools

REST API (Layer & Feature Queries)

Geocoding

Height Service

STAC Catalog (Geodata Downloads)

WMTS (Map URLs)

OEREB Cadastre

Consolidated Geodata Façade

Administrative Address Level (OpenPLZ)

Example Use Cases

Architecture

Project Structure

Security & Compliance

Phase

Tool budget and aggregation

Data sources and licences

Project structure

Lethal Trifecta assessment

Egress

Container deployment

MCP Protocol Version

Sessions & Authentication

Error handling

MCP Primitives

Tool workflows

Response Format

Known Limitations

Known findings — OpenPLZ live probe (2026-07-20)

Testing

Changelog

Contributing

Security

License

Author

Credits & Related Projects

Installation

Comments (0)