F
licenseNot graded
qualityC
maintenanceExposes ATTOM's real estate API as MCP tools, enabling property details, valuations, assessments, sales, and area data via natural language.
2
-
swiss-housing-mcp
by malkreide
swiss-housing-mcp
属于 Swiss Public Data MCP Portfolio 的一部分 — 连接 AI 代理与瑞士公共数据的开源 MCP 服务器。私人项目，与任何雇主或机构无关。
用于瑞士联邦建筑与住宅登记册 (GWR/RegBL) 的 MCP 服务器 — 建筑、住宅和建设管线
🎯 锚点演示查询
«自 2020 年以来苏黎世市新建了多少套住宅，其中 4 室及以上的有多少套——目前又有多少套正在建设中？»
已针对 2026-07-24 的实时数据转储进行验证：自 2020 年以来新建住宅 16'164 套（其中 27.4% 为 4 室及以上——家庭住房的代理指标），以及目前正在建设的 7'287 套住宅。今天正在建设的住宅就是 1–3 年后的家庭：这是学校空间规划的早期指标。
演示
Related MCP server: swiss-statistics-mcp
概述
GWR/RegBL 之于建筑，正如 Zefix 之于公司：它不是众多数据源之一，而是联邦登记册，其标识符（建筑的 EGID、住宅的 EWID）在瑞士行政数据中充当连接键。该服务器通过 MCP 工具公开登记册的公共提取数据——建筑查询、地址地理编码、按市镇划分的建设统计、市镇以下边界框分析，以及规划/建设管线。
address_to_egid 是使其他数据源具备 EGID 能力的插头：输入地址，输出联邦标识符和 LV95 坐标。
架构决策
该服务器使用架构 B（混合：优先转储，API 回退）。
理由（已于 2026-07-24 实时验证）：
公共州级转储（
public.madd.bfs.admin.ch/{canton}.zip）每日刷新（约 05:30 CET），并附带现成的data.sqlite，包含表building（ZH 有 399'830 行）、entrance、dwelling（ZH 有 894'631 行）和code。无需 CSV 解析，无需认证。api3.geo.admin.ch（find / identify / SearchServer）无需认证即可可靠地用于单实体查询和地理编码，但无法扩展到区域级聚合（结果限制）。在
/api/buildings/{egid}探测的 MADD REST 端点返回 404；在路径和认证状态明确之前将其排除——这不是障碍，因为所有第一阶段工具无需它即可工作。
后果：
州级转储在磁盘上缓存，TTL 为 24 小时（可通过
SWISS_HOUSING_DUMP_TTL_HOURS配置）。聚合和空间查询以只读 SQL 方式针对缓存的 SQLite 运行；单次查询和地理编码则访问实时 API。
每个响应都带有
source（归属）和provenance（daily_dump|live_api|cached）。
实时探测结果（2026-07-24）
端点 | HTTP | 状态 | 备注 |
| 200 | ✅ 可用 | 完整属性集，无需认证 |
| 200 | ✅ 可用 | 77 个属性，包括 EGID/EWID |
| 200 | ✅ 可用 |
|
| 200 | ✅ 可用 | 121 MB，每日刷新，包含 |
| 404 | ❌ 已排除 | 路径/认证不明确 |
无效 EGID 的 find 查询 | 200 | ⚠️ 软错误 | 空的 |
功能
lookup_building(egid)— 按联邦标识符查询单个建筑（实时 API）address_to_egid(address)— 将任何瑞士地址地理编码为 EGID/EDID + LV95lookup_dwellings(egid)— 建筑的所有住宅，包含房间数、面积、楼层new_construction(municipality_bfs, since_year)— 年度新建住宅，包括 4 室及以上家庭住房占比construction_pipeline(municipality_bfs)— 已规划 / 已批准 / 正在建设buildings_in_bbox(e_min, n_min, e_max, n_max)— 市镇以下分析（例如学区）municipality_housing_stats(municipality_bfs)— 住房存量和房间大小构成explain_code(attribute, code)— 通过官方 DE/FR/IT 代码表解码 GWR 代码dump_status()— 缓存新鲜度，优雅降级入口点
先决条件
Python 3.10+
每个缓存的州级转储约需 130 MB 磁盘空间（ZH）
无需 API 密钥——第一阶段无需认证
安装
uvx swiss-housing-mcp # once published on PyPI
# or from source
pip install -e .用法 / 快速开始
Claude Desktop（claude_desktop_config.json）：
{
"mcpServers": {
"swiss-housing": {
"command": "uvx",
"args": ["swiss-housing-mcp"]
}
}
}云（Render/Railway）：
SWISS_HOUSING_TRANSPORT=streamable-http PORT=8000 swiss-housing-mcp配置
变量 | 默认值 | 用途 |
|
|
|
|
| 转储缓存目录 |
|
| 转储新鲜度窗口 |
MCP 协议版本
该服务器在同一端点上支持两个协议时代。客户端在连接上的第一个请求决定适用哪个时代；之后来自另一个时代的声明将被拒绝。
时代 | 修订版本 | 谁使用它 |
|
| 当今客户端使用的版本。服务器以所请求的修订版本应答，或者当请求要求更新版本时，以 |
每请求封套 |
| 携带 |
两个修订版本都固定在 tests/test_protocol_version.py 中，并针对已安装的 SDK 进行断言，因此 Dependabot 对 mcp 的升级不会悄悄移动任何一个。该服务器不构建 ASGI 应用来发送 initialize，因此该门禁断言的是 SDK 常量，而不是实测响应——这是较弱的形式，但明确说明而非含糊其辞。
请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而不是握手时代——仅针对它进行固定会让当前客户端实际协商的时代自由漂移。
更新策略。 当门禁失败时，不要盲目编辑常量：阅读两个修订版本之间的规范变更日志，验证服务器仍然正常工作，然后一起移动常量、本节、README.de.md 和 CHANGELOG.md。
测试
PYTHONPATH=src pytest tests/ -m "not live" # CI-safe
PYTHONPATH=src pytest tests/ -m live # against real upstream项目结构
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已知限制
公共提取数据省略了完整 GWR 中与人员相关及部分敏感属性；向官方机构的数据交付通过 BFS/MADD 渠道进行。
坐标是建筑参考点（LV95），而非占地多边形——多边形连接（例如精确的学区边界）需要外部几何数据；
buildings_in_bbox覆盖矩形近似。GBAUJ（建造年份）在部分较旧建筑中缺失；期间代码（GBAUP）作为回退存在，但尚未公开。市镇→州的分辨率已为常见情况预置；其他情况请显式传递
canton。住房市场指数（IMPI、建筑价格指数、空置率）特意放在
swiss-statistics-mcp中——该服务器是登记层，而非统计层。
变更日志
参见 CHANGELOG.md
贡献
欢迎贡献——参见 CONTRIBUTING.md（Deutsch）。
安全
只读、无个人身份信息、无需认证——通过一组固定端点访问的公共联邦登记册。完整的安全态势及如何报告漏洞，请参见 SECURITY.md（Deutsch）。
许可证
MIT 许可证——参见 LICENSE。数据：GWR/RegBL，瑞士联邦统计局（BFS），开放政府数据，需注明出处。
作者
Hayal Oezkan · github.com/malkreide
致谢与相关项目
组合中的姊妹项目：
swiss-statistics-mcp（指数、STAT-TAB）、zurich-opendata-mcp（城市级数据）
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| canton | No | ||
| municipality_bfs | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| note | No | |
| source | No | |
| pipeline | Yes | |
| provenance | Yes | |
| municipality | Yes | |
| municipality_bfs | Yes |
TDQS
B3.4/5.0
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters1/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| dumps | Yes | |
| source | No | |
| ttl_hours | Yes | |
| provenance | Yes |
TDQS
A3.9/5.0
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| canton | No | zh | |
| attribute | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| source | No | |
| provenance | Yes | |
| explanations | Yes |
TDQS
A3.7/5.0
Behavior4/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| egid | Yes | ||
| canton | No | zh |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| egid | Yes | |
| count | Yes | |
| source | No | |
| dwellings | Yes | |
| provenance | Yes |
TDQS
A3.5/5.0
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| canton | No | ||
| since_year | No | ||
| municipality_bfs | Yes |
Output Schema
ParametersJSON 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
B3/5.0
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters2/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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
A3.6/5.0
Scored across 5 tools
Disambiguation5/5
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.
Naming Consistency3/5
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.
Tool Count5/5
Five tools is well-scoped for a niche domain like Swiss housing data. Each tool serves a clear function without excess or deficiency.
Completeness4/5
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
ActivityActive
ResponsivenessNo issues
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
- 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