swiss-housing-mcp

Part of the Swiss Public Data MCP Portfolio — open-source MCP servers connecting AI agents to Swiss public data. Private project, independent of any employer or institutional affiliation.

MCP server for the Swiss Federal Register of Buildings and Dwellings (GWR/RegBL) — buildings, dwellings, and the construction pipeline

🇩🇪 Deutsche Version

---

🎯 Anchor Demo Query

«How many dwellings were newly built in the City of Zurich since 2020, how many with 4+ rooms — and how many are currently under construction?»

Verified against the live dump on 2026-07-24: 16'164 new dwellings since 2020 (27.4% with 4+ rooms — the family-housing proxy), and 7'287 dwellings currently under construction. Dwellings under construction today are households in 1–3 years: the early indicator for school-space planning.

---

Overview

The GWR/RegBL is to buildings what Zefix is to companies: not one data source among many, but the federal register whose identifiers (EGID for buildings, EWID for dwellings) serve as join keys across Swiss administrative data. This server exposes the register's public extract through MCP tools — building lookups, address geocoding, per-municipality construction statistics, sub-municipal bounding-box analysis, and the planning/construction pipeline.

address_to_egid is the plug that makes other data sources EGID-capable: address in, federal identifier and LV95 coordinates out.

Architecture decision

This server uses Architecture B (Hybrid: Dump-first, API-fallback).

Rationale (verified live on 2026-07-24):

• The public cantonal dump (public.madd.bfs.admin.ch/{canton}.zip) is refreshed daily (~05:30 CET) and ships a ready-made data.sqlite with tables building (399'830 rows for ZH), entrance, dwelling (894'631 rows for ZH), and code. No CSV parsing, no auth.
• api3.geo.admin.ch (find / identify / SearchServer) works reliably without authentication for single-entity lookups and geocoding, but does not scale to area-wide aggregations (result limits).
• A MADD REST endpoint probed at /api/buildings/{egid} returned 404; it is excluded until path and auth status are clarified — no blocker, since all Phase-1 tools work without it.

Consequences:

• Cantonal dumps are cached on disk with a 24 h TTL (configurable via SWISS_HOUSING_DUMP_TTL_HOURS).
• Aggregations and spatial queries run as read-only SQL against the cached SQLite; single lookups and geocoding hit the live API.
• Every response carries source (attribution) and provenance (daily_dump | live_api | cached).

Live probe findings (2026-07-24)

Endpoint	HTTP	Status	Note
api3.geo.admin.ch …/find (EGID lookup)	200	✅ works	full attribute set, no auth
api3.geo.admin.ch …/identify (coordinates)	200	✅ works	77 attributes incl. EGID/EWID
…/SearchServer (address → EGID)	200	✅ works	featureId = {EGID}_{EDID}; axis swap: y=east, x=north
public.madd.bfs.admin.ch/zh.zip	200	✅ works	121 MB, daily refresh, contains data.sqlite
madd.bfs.admin.ch/api/buildings/{egid}	404	❌ excluded	path/auth unclear
Invalid EGID on find	200	⚠️ soft error	empty results array — not an HTTP error

Features

• lookup_building(egid) — single building by federal identifier (live API)
• address_to_egid(address) — geocode any Swiss address to EGID/EDID + LV95
• lookup_dwellings(egid) — all dwellings of a building with rooms, area, floor
• new_construction(municipality_bfs, since_year) — yearly new construction incl. 4+ room family-housing share
• construction_pipeline(municipality_bfs) — projected / approved / under construction
• buildings_in_bbox(e_min, n_min, e_max, n_max) — sub-municipal analysis (e.g. school districts)
• municipality_housing_stats(municipality_bfs) — housing stock and room-size mix
• explain_code(attribute, code) — decode GWR codes via the official DE/FR/IT code table
• dump_status() — cache freshness, graceful-degradation entry point

Prerequisites

• Python 3.10+
• ~130 MB disk per cached cantonal dump (ZH)
• No API keys — Phase 1 is authentication-free

Installation

uvx swiss-housing-mcp        # once published on PyPI

# or from source
pip install -e .

Usage / Quickstart

Claude Desktop (claude_desktop_config.json):

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

Cloud (Render/Railway):

SWISS_HOUSING_TRANSPORT=streamable-http PORT=8000 swiss-housing-mcp

Configuration

Variable	Default	Purpose
SWISS_HOUSING_TRANSPORT	stdio	stdio | streamable-http | sse
SWISS_HOUSING_CACHE	~/.cache/swiss-housing-mcp	Dump cache directory
SWISS_HOUSING_DUMP_TTL_HOURS	24	Dump freshness window

Testing

PYTHONPATH=src pytest tests/ -m "not live"   # CI-safe
PYTHONPATH=src pytest tests/ -m live         # against real upstream

Project Structure

swiss-housing-mcp/
├── src/swiss_housing_mcp/
│   ├── server.py      # FastMCP tools (9)
│   ├── gwr.py         # Dump store + geo.admin.ch client + retry
│   ├── models.py      # Pydantic v2 envelopes (source + provenance)
│   └── __main__.py    # Dual-transport entry point
├── tests/             # respx-mocked + @pytest.mark.live
└── .github/workflows/ # CI + OIDC PyPI publish

Known Limitations

• The public extract omits person-related and some sensitive attributes of the full GWR; official data deliveries to authorities go through the BFS/MADD channel.
• Coordinates are building reference points (LV95), not footprint polygons — polygon joins (e.g. exact school-district boundaries) need external geometries; buildings_in_bbox covers the rectangular approximation.
• GBAUJ (construction year) is missing for a share of older buildings; period codes (GBAUP) exist as fallback but are not yet exposed.
• Municipality→canton resolution is seeded for common cases; pass canton explicitly for others.
• Housing-market indices (IMPI, construction price index, vacancy rate) deliberately live in swiss-statistics-mcp — this server is the register layer, not the statistics layer.

Changelog

See CHANGELOG.md

License

MIT License — see LICENSE. Data: GWR/RegBL, Swiss Federal Statistical Office (BFS), open government data with attribution.

Credits & Related Projects

• Data: Federal Statistical Office — GWR/RegBL, geo.admin.ch
• Portfolio siblings: swiss-statistics-mcp (indices, STAT-TAB), zurich-opendata-mcp (city-level data)

Author

malkreide · GitHub