swiss-housing-mcp

swiss-housing-mcp

属于 Swiss Public Data MCP Portfolio — 连接 AI Agent 与瑞士公共数据的开源 MCP 服务。私人项目，与任何雇主或机构均无关联。

瑞士联邦建筑物与住宅登记册（GWR/RegBL）的 MCP 服务 — 建筑物、住宅及建设项目管线

🇩🇪 德语版

---

🎯 示例演示查询

«自 2020 年以来，苏黎世市新建了多少套住宅，其中有多少套有 4 个及以上房间？目前又有多少套正在建设中？»

根据 2026-07-24 的实时数据转储核验：自 2020 年以来共有 16'164 套新建住宅（其中 27.4% 有 4 个及以上房间，可作为家庭住房的近似指标），目前有 7'287 套住宅正在建设中。如今正在建设的住宅将在 1–3 年后成为家庭住所，也是学校空间规划的早期指标。

演示

---

概述

对于建筑物而言，GWR/RegBL 就如同 Zefix 对于公司：它并非众多数据源之一，而是联邦登记册，其标识符（建筑物使用 EGID，住宅使用 EWID）是瑞士各类行政数据的关联键。此服务通过 MCP 工具提供该登记册的公开摘录 — 建筑物查询、地址地理编码、按市镇统计建设数据、市镇内边界框分析，以及规划与建设项目管线。

address_to_egid 是让其他数据源支持 EGID 的关键：输入地址，输出联邦标识符和 LV95 坐标。

架构决策

此服务采用 架构 B（混合模式：优先使用数据转储，API 作为后备）。

理由（已于 2026-07-24 实时核验）：

• 公开的州级数据转储（public.madd.bfs.admin.ch/{canton}.zip）每天更新一次（约 CET 05:30），并提供现成的 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	状态	备注
api3.geo.admin.ch …/find（EGID 查询）	200	✅ 正常	完整属性集，无需身份验证
api3.geo.admin.ch …/identify（坐标）	200	✅ 正常	77 个属性，包括 EGID/EWID
…/SearchServer（地址 → EGID）	200	✅ 正常	featureId = {EGID}_{EDID}；轴顺序互换：y=东向，x=北向
public.madd.bfs.admin.ch/zh.zip	200	✅ 正常	121 MB，每日更新，包含 data.sqlite
madd.bfs.admin.ch/api/buildings/{egid}	404	❌ 不纳入	路径和身份验证状态不明确
find 中的无效 EGID	200	⚠️ 软错误	results 数组为空 — 并非 HTTP 错误

功能

• lookup_building(egid) — 按联邦标识符查询单栋建筑（实时 API）
• address_to_egid(address) — 将任意瑞士地址地理编码为 EGID/EDID + LV95
• lookup_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+
• 每份缓存的州级数据转储（ZH）约需 130 MB 磁盘空间
• 无需 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

配置

变量	默认值	用途
SWISS_HOUSING_TRANSPORT	stdio	stdio | streamable-http | sse
SWISS_HOUSING_CACHE	~/.cache/swiss-housing-mcp	数据转储缓存目录
SWISS_HOUSING_DUMP_TTL_HOURS	24	数据转储的新鲜度时间窗口

MCP 协议版本

此服务通过同一端点支持两个协议时代。客户端在连接上的首次请求决定适用的协议；之后若另一时代提出不同声明，则会被拒绝。

时代	版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的版本。服务会返回请求中指定的版本；若请求的版本更新，则返回 2025-11-25 上限版本。
每请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会开启现代连接。

这两个时代都经过实测，而非推断： tests/test_modern_era.py 会通过此服务自身的 ASGI 应用，发送每个时代的真实请求；该应用由 __main__.py 在 SWISS_HOUSING_TRANSPORT=streamable-http 时提供服务。测试会从响应正文中读取协商后的版本。 此外，tests/test_protocol_version.py 会将两个版本与已安装的 SDK 进行校验，因此 Dependabot 升级 mcp 时，会在任何人查看测量结果之前导致构建失败。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名 — 仅针对它进行校验，会让当前客户端实际协商的时代版本不受约束地漂移。

现代时代的身份信息。 2026-07-28 时代没有 initialize 握手：连接由一个携带 _meta 信封的请求构成。因此，server/discover 是现代客户端了解此服务的唯一渠道，而 SDK 添加到每个结果中的 serverInfo 块是其身份信息唯一出现的位置。因此，此服务会声明 version、title、description、websiteUrl 和 instructions。description 和 websiteUrl 从软件包元数据中读取，而非重复写成字面值 — SDK 不会填充这些字段；未指定版本的服务则会在每个响应中都报告空的 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）。

安全

只读、不含 PII、无需身份验证——通过一组固定端点访问公开的联邦登记册。完整的安全说明及漏洞报告方式，请参阅 SECURITY.md（Deutsch）。

许可证

MIT License——请参阅 LICENSE。数据：GWR/RegBL，瑞士联邦统计局（BFS），注明出处即可使用的开放政府数据。

作者

Hayal Oezkan · github.com/malkreide

致谢与相关项目

• 数据：联邦统计局 — GWR/RegBL，geo.admin.ch
• 同系列项目：swiss-statistics-mcp（指数、STAT-TAB），zurich-opendata-mcp（市级数据）