swiss-housing-mcp
This server provides access to the Swiss Federal Register of Buildings and Dwellings (GWR/RegBL), enabling AI agents to query building data, geocode addresses, analyze construction trends, and decode official register codes.
Look up a building by its federal identifier (EGID): get address, LV95 coordinates, status, category, floor area, dwelling count, and construction year.
Geocode addresses: convert Swiss addresses to EGID/EDID and LV95 coordinates.
List dwellings: retrieve all dwellings in a building with rooms, floor area, floor level, and construction year.
New construction statistics: for a municipality, get yearly counts of new buildings, dwellings, and 4+ room dwellings (family housing proxy) since a given year.
Construction pipeline: see buildings and dwellings currently projected, approved, or under construction in a municipality.
Spatial queries: aggregate building and dwelling counts inside an LV95 bounding box for sub‑municipal analysis (e.g. school districts).
Municipality housing stats: get an overview of housing stock: total buildings, residential buildings, total dwellings, and breakdown by room count.
Decode GWR codes: translate numeric GWR codes into human‑readable labels in German, French, and Italian.
Check cache status: inspect freshness of cantonal data dumps and configured TTL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@swiss-housing-mcpHow many new dwellings in Zurich since 2020?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
🎯 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.
Demo
Related MCP server: swiss-statistics-mcp
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-madedata.sqlitewith tablesbuilding(399'830 rows for ZH),entrance,dwelling(894'631 rows for ZH), andcode. 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) andprovenance(daily_dump|live_api|cached).
Live probe findings (2026-07-24)
Endpoint | HTTP | Status | Note |
| 200 | ✅ works | full attribute set, no auth |
| 200 | ✅ works | 77 attributes incl. EGID/EWID |
| 200 | ✅ works |
|
| 200 | ✅ works | 121 MB, daily refresh, contains |
| 404 | ❌ excluded | path/auth unclear |
Invalid EGID on find | 200 | ⚠️ soft error | empty |
Features
lookup_building(egid)— single building by federal identifier (live API)address_to_egid(address)— geocode any Swiss address to EGID/EDID + LV95lookup_dwellings(egid)— all dwellings of a building with rooms, area, floornew_construction(municipality_bfs, since_year)— yearly new construction incl. 4+ room family-housing shareconstruction_pipeline(municipality_bfs)— projected / approved / under constructionbuildings_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 mixexplain_code(attribute, code)— decode GWR codes via the official DE/FR/IT code tabledump_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-mcpConfiguration
Variable | Default | Purpose |
|
|
|
|
| Dump cache directory |
|
| Dump freshness window |
MCP Protocol Version
This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.
Era | Revision | Who reaches it |
|
| What today's clients speak. The server answers with the revision asked for, or with the |
Per-request envelope |
| A request carrying the |
Both revisions are pinned in
tests/test_protocol_version.py and asserted
against the installed SDK, so a Dependabot bump of mcp cannot move either one
silently. This server builds no ASGI app to send an initialize through, so
the gate asserts the SDK constants rather than a measured response — the
weaker form, named rather than left unsaid.
Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern
era, not for the handshake era — pinning against it alone would leave the era
that current clients actually negotiate free to drift.
Update policy. When the gate fails, do not edit the constant blindly: read
the spec changelog between the two revisions, verify the server still behaves,
then move the constant, this section, README.de.md and
CHANGELOG.md together.
Testing
PYTHONPATH=src pytest tests/ -m "not live" # CI-safe
PYTHONPATH=src pytest tests/ -m live # against real upstreamProject 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 publishKnown 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_bboxcovers 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
cantonexplicitly 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
Contributing
Contributions are welcome — see CONTRIBUTING.md (Deutsch).
Security
Read-only, no PII, no authentication — a public federal register accessed through a fixed set of endpoints. See SECURITY.md (Deutsch) for the full posture and how to report a vulnerability.
License
MIT License — see LICENSE. Data: GWR/RegBL, Swiss Federal Statistical Office (BFS), open government data with attribution.
Author
Hayal Oezkan · github.com/malkreide
Credits & Related Projects
Portfolio siblings:
swiss-statistics-mcp(indices, STAT-TAB),zurich-opendata-mcp(city-level data)
Available Tools
5 toolsconstruction_pipelineBRead-only
Buildings and dwellings in the planning/construction pipeline of a municipality.
Breaks down by status: projected (GSTAT 1001), approved (1002), under construction (1003). Dwellings under construction today are households in 1-3 years — the early indicator for school-space planning.
| Name | Required | Description | Default |
|---|---|---|---|
| canton | No | ||
| municipality_bfs | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| note | No | |
| source | No | |
| pipeline | Yes | |
| provenance | Yes | |
| municipality | Yes | |
| municipality_bfs | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's additional information about status breakdowns and the interpretation of 'under construction' as an early indicator adds useful behavioral context. However, it does not disclose potential limitations like data availability by municipality or time-range constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: the first states the core purpose, the second details the status categories, and the third explains the practical implication. Every sentence adds value, and the content is front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's moderate complexity, the description covers the data meaning and use case. However, it omits parameter semantics and does not specify what the output contains or how to interpret the status codes fully (though codes are listed). The description is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its two parameters (canton, municipality_bfs). The description does not mention these parameters or provide any guidance on their values, formats, or roles. With no schema descriptions and no parameter information in the description, the agent receives no help beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool retrieves buildings and dwellings in the planning/construction pipeline of a municipality, with explicit breakdowns by status codes. This verb-resource combination is distinct from sibling tools like lookup_dwellings (likely existing dwelling data) and new_construction (new building registrations). The context of early indicator for school-space planning further differentiates its use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting pipeline data for a municipality and hints at its value for school-space planning, but it does not explicitly state when to prefer this tool over siblings or when not to use it. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
dump_statusARead-only
Cache status of the cantonal GWR dumps (graceful-degradation entry point).
Always returns an evaluable status — never silently empty records. If a source is unreachable, this tool tells you when data was last refreshed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| dumps | Yes | |
| source | No | |
| ttl_hours | Yes | |
| provenance | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds value by stating the tool never returns empty records and reports last refresh time, which is beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The key information is front-loaded and every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and the existence of an output schema, the description adequately covers the tool's behavior and return value. It is sufficient for the agent to understand what to expect, though it doesn't detail the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the baseline is 4. The description correctly adds no parameter information since none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows cache status of GWR dumps with graceful degradation. It is distinct from sibling tools like lookup_dwellings which retrieve data. No explicit differentiation from siblings, but the purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking cache health even when sources are unreachable, but does not explicitly state when to use it over alternatives. It provides context but no exclusions or direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explain_codeARead-only
Decode a GWR code value (e.g. GSTAT=1004, GKAT=1020) into human-readable labels.
Uses the official code table shipped with the dump (DE/FR/IT).
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| canton | No | zh | |
| attribute | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| source | No | |
| provenance | Yes | |
| explanations | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds value by specifying the source of the labels (official code table) and the supported languages (DE/FR/IT), going beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at two sentences, but the second sentence could be more structured or broken into bullet points for clarity. No superfluous information, but room for slight improvement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 params, no enums) and the presence of an output schema, the description adequately covers the main purpose. However, it lacks explanation for the optional parameter and does not mention the output schema's structure, resulting in moderate completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description bears the full burden of explaining parameters. It includes an example of 'attribute' and 'code' but does not describe the optional 'canton' parameter at all, leaving a gap in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool decodes GWR code values into human-readable labels, with a specific verb and resource. It provides an example of inputs (GSTAT=1004) and distinguishes itself from sibling tools that handle different tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for decoding codes from a specific code table, but does not explicitly state when to use this tool vs alternatives, nor does it mention any prerequisites or when not to use it. Sibling tools have different purposes, so some implicit differentiation exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
lookup_dwellingsARead-only
List all dwellings (EWID) of a building from the daily cantonal dump.
Includes rooms, floor area, floor and status per dwelling.
| Name | Required | Description | Default |
|---|---|---|---|
| egid | Yes | ||
| canton | No | zh |
Output Schema
| Name | Required | Description |
|---|---|---|
| egid | Yes | |
| count | Yes | |
| source | No | |
| dwellings | Yes | |
| provenance | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds context (data source 'daily cantonal dump' and included fields) but does not disclose behavior beyond that, such as error handling or permissions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the core action. However, it could be slightly more structured with bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with an output schema, the description adequately mentions included fields but omits explanation of the required 'egid' parameter and the default value for 'canton'. The data source reference is vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain parameters. However, it does not mention 'egid' as building ID or 'canton''s role. It only references 'a building' implicitly, leaving parameter semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all dwellings (EWID) of a building' and specifies included attributes (rooms, floor area, floor, status). This distinguishes it from sibling tools like new_construction or dump_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicit. The description does not mention when to use this tool versus alternatives, nor does it provide conditions for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
new_constructionBRead-only
New residential construction per year for a municipality (existing buildings).
Returns buildings, dwellings and 4+ room dwellings per year — the 4+ room share is a proxy for family housing and thus for future pupil numbers. Municipality is identified by its BFS number (e.g. 261 = City of Zurich).
| Name | Required | Description | Default |
|---|---|---|---|
| canton | No | ||
| since_year | No | ||
| municipality_bfs | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| source | No | |
| per_year | Yes | |
| provenance | Yes | |
| since_year | Yes | |
| municipality | Yes | |
| total_dwellings | Yes | |
| family_share_pct | Yes | Share of 4+ room dwellings — proxy for family housing |
| municipality_bfs | Yes | |
| total_dwellings_4plus_rooms | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds context about the 4+ room share being a proxy for family housing, but does not disclose any additional behavioral traits such as data source, update frequency, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two sentences, efficiently conveying core purpose and a key interpretation note. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return value explanation is not needed. However, the description lacks usage context and does not fully cover parameters. Adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description only explains municipality_bfs with an example. Parameters canton and since_year are not described at all, leaving their semantics unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns annual new residential construction data for a municipality, including buildings, dwellings, and 4+ room dwellings. However, phrasing 'existing buildings' may cause confusion about whether it covers new construction or existing stock.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like lookup_dwellings or construction_pipeline. Does not mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
5 tool updates
v0.1.0- First observed
construction_pipeline - First observed
dump_status - First observed
explain_code - First observed
lookup_dwellings - First observed
new_construction
TDQS
Scored across 5 tools
Each tool targets a distinct aspect: listing dwellings, historical construction, pipeline, code explanation, and cache status. There is no overlap or ambiguity in their purposes.
Tool names mix patterns: verb_noun (lookup_dwellings, explain_code), adjective_noun (new_construction), and noun_noun (construction_pipeline, dump_status). While readable, the lack of a uniform pattern reduces consistency.
Five tools is well-scoped for a niche domain like Swiss housing data. Each tool serves a clear function without excess or deficiency.
The tools cover current dwelling data, historical construction, future pipeline, code decoding, and system status. A minor gap is the lack of a dedicated building-level query beyond dwellings, but the set supports the stated planning use case.
Maintenance
Related MCP Connectors
- geoOAuthco.thinair
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
CompanyLens is a remote MCP server giving AI agents instant access to official company registry data across 19 jurisdictions in Europe, the Americas, and Asia-Pacific. Eighteen read-only tools let you search companies and people, look up officers and beneficial owners, map corporate networks through shared directors, screen names against the UK disqualified directors register, find every company at a registered address, and pull filing history — all from a single connector. Visit our website: https://companylens.io
Agent-native MCP server over 49M+ US public and government records, privacy-first, always current.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceExposes ATTOM's real estate API as MCP tools, enabling property details, valuations, assessments, sales, and area data via natural language.2-
- AlicenseAqualityAmaintenanceProvides AI-native access to Swiss Federal Statistical Office datasets through 9 tools for querying education, population, and cross-cantonal comparisons without authentication.152MIT
- AlicenseBqualityDmaintenanceMCP server exposing all major Swiss official public APIs as native tools for any MCP-compatible AI agent.345 npmMIT
- AlicenseAqualityAmaintenanceMCP server for Switzerland's national metadata catalogue, enabling AI agents to discover datasets, APIs, public services, and publishers through free-text search and structured queries.13MIT