swiss-road-mobility-mcp

🇨🇭 属于 Swiss Public Data MCP Portfolio

🚗 Swiss Road & Mobility MCP Server

用于瑞士道路交通的 MCP 服务——共享车辆、电动汽车充电、交通警报、Park & Rail，以及多模式行程规划

🇩🇪 德语版

---

演示

---

概览

swiss-road-mobility-mcp 提供对瑞士道路和交通数据源的 AI 原生访问：

来源	数据	API	身份验证
sharedmobility.ch	自行车、电动滑板车、汽车（GBFS）	REST/JSON	无
ich-tanke-strom.ch	电动汽车充电站	GeoJSON	无
opentransportdata.swiss	交通事件、计数站	DATEX II / SOAP+XML	免费密钥
data.sbb.ch	Park & Rail 设施	REST/JSON（Opendatasoft）	无
transport.opendata.ch	公共交通线路	REST/JSON	无
geo.admin.ch	地址地理编码、道路分类	REST/JSON	无

如果 Swiss Transport MCP 是铁路的 GA 通票，那么此服务就是道路出行的高速公路年票、Park & Rail 卡和共享交通订阅；两者结合可呈现瑞士交通完整的多模式图景。

核心演示查询： “我在 Dietikon，有车。我需要去 Bern。哪里可以停车？我该坐哪趟火车？”

---

功能

• 覆盖六个数据源的 15 个工具（阶段 1–4）
• road_mobility_snapshot — 汇总任意地点的交通概况
• road_multimodal_plan — 在一份方案中规划汽车、Park & Rail 和公共交通
• 15 个工具中有 12 个无需 API 密钥
• 双传输方式——stdio（Claude Desktop）+ SSE（云端）
• 为所有端点提供速率限制和缓存

---

先决条件

• Python 3.11+
• uv（推荐）或 pip

---

安装

# Clone the repository
git clone https://github.com/malkreide/swiss-road-mobility-mcp.git
cd swiss-road-mobility-mcp

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

或使用 uvx（无需永久安装）：

uvx swiss-road-mobility-mcp

---

快速开始

# stdio (for Claude Desktop)
swiss-road-mobility-mcp
# or:
python -m swiss_road_mobility_mcp.server

# Streamable HTTP (for cloud / Render.com) — serves MCP 2026-07-28 at /mcp
# and keeps the legacy SSE routes alongside.
MCP_TRANSPORT=http MCP_PORT=8001 swiss-road-mobility-mcp

在 Claude Desktop 中立即试用：

“显示 Zurich HB 附近所有与交通出行相关的信息。” “查找 Bern Bahnhof 附近的共享自行车。” “Lucerne 附近哪里可以给我的电动汽车充电？”

→ 按受众分类的更多用例 →

---

配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "swiss-road-mobility": {
      "command": "uvx",
      "args": ["swiss-road-mobility-mcp"],
      "env": {
        "OPENTRANSPORTDATA_API_KEY": "<your-token>"
      }
    }
  }
}

或使用 python：

{
  "mcpServers": {
    "swiss-road-mobility": {
      "command": "python",
      "args": ["-m", "swiss_road_mobility_mcp.server"],
      "env": {
        "OPENTRANSPORTDATA_API_KEY": "<your-token>"
      }
    }
  }
}

共享交通、电动汽车充电、Park & Rail 和多模式规划工具无需 OPENTRANSPORTDATA_API_KEY。只有 DATEX II 交通工具需要此密钥。

配置文件位置：

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

云端部署（用于浏览器访问的 SSE）

通过浏览器中的 claude.ai 使用（例如，在没有本地软件的受管工作站上）：

Render.com（推荐）：

1. 将仓库推送到 GitHub，或在 GitHub 上派生该仓库
2. 在 render.com 上：新建 Web Service -> 连接 GitHub 仓库
3. 设置启动命令：MCP_TRANSPORT=http MCP_PORT=8001 swiss-road-mobility-mcp
4. 在 claude.ai 的 Settings -> MCP Servers 中，添加 https://your-app.onrender.com/mcp — 对于仍使用 SSE 传输的客户端，也可以使用 .../sse；http 会同时提供两者。

SSE 安全性（SEC-009）

任何人都可以访问公开的 SSE 端点。要保护该端点（以及你的上游 API 配额），请在主机上配置以下环境变量：

变量	作用
MCP_AUTH_TOKEN	设置后，每个 SSE 请求都必须发送 Authorization: Bearer <token>。未设置 = 无需身份验证（服务器启动时会记录醒目的警告）。强烈建议在任何公开部署中设置。
MCP_RATE_LIMIT	每个客户端 IP 在每个时间窗口内的最大请求数（默认为 60，0 表示禁用）。
MCP_RATE_WINDOW	时间窗口长度，单位为秒（默认为 60）。
ALLOWED_ORIGINS	用逗号分隔的浏览器客户端 CORS 来源。默认为空：不允许跨域访问。 * 表示允许任何来源，并会记录警告。不影响 stdio 或其他非浏览器客户端。

本地 stdio 传输无需配置这些内容——它在用户受信任的上下文中运行。

可观测性（OBS-003 / OBS-006）

变量	作用
MCP_LOG_LEVEL	日志级别：DEBUG / INFO（默认）/ WARNING / ERROR。
MCP_LOG_FORMAT	使用 text（默认）或 json 输出结构化日志。所有日志都输出到 stderr。
MCP_TRACING_ENABLED	设为 true 可启用 OpenTelemetry 跟踪（默认关闭）。
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 收集器 URL；设置此变量也会启用跟踪。SDK 会识别标准的 OTEL_* 变量。

跟踪需要安装可选扩展：pip install 'swiss-road-mobility-mcp[tracing]'。 启用后，系统会自动跟踪每次上游 API 调用（通过 httpx 插桩），并为 SSE 请求生成服务器 span，同时传播 W3C 跟踪上下文。

---

可用工具

共享出行与电动汽车充电（无需 API 密钥）

工具	描述	缓存
road_find_sharing	查找附近的共享出行服务（自行车、电动滑板车、汽车）	60s
road_search_sharing	按名称搜索共享出行站点	5min
road_sharing_providers	瑞士境内的所有共享出行服务提供商	1h
road_find_charger	查找附近的电动汽车充电站	5min
road_charger_status	充电站的实时可用情况	1min
road_check_status	服务器与 API 健康检查	-

交通（需要免费的 API 密钥）

工具	描述	缓存
road_traffic_situations	ASTRA/VMZ-CH 提供的事故、道路施工、交通拥堵信息	2min
road_traffic_counters	位置附近计数站的车辆数/小时及公里/小时数据	1min
road_counter_sites	列出附近的计数站	24h

停车换乘与多模式出行（无需 API 密钥）

工具	描述	缓存
road_park_rail	查找附近的 SBB 停车换乘设施	5min
road_mobility_snapshot	获取某地点的完整出行概览	-
road_multimodal_plan	规划汽车 -> 停车换乘 -> 公共交通 -> 目的地的行程	-

地理与地址 — 第 4 阶段（无需 API 密钥）

工具	描述	缓存
road_geocode_address	瑞士地址 -> GPS（官方建筑地址登记册）	-
road_reverse_geocode	GPS -> 含 EGID/EGAID 的官方地址（GWR）	-
road_classify_road	通过 swissTLM3D 对道路进行分类	-

使用示例

查询	工具
“查找苏黎世 HB 附近的共享自行车”	road_find_sharing
“伯尔尼附近哪里可以给电动汽车充电？”	road_find_charger
“A1 公路上有交通事故吗？”	road_traffic_situations
“温特图尔车站附近哪里可以停车？”	road_park_rail
“规划从迪蒂孔到伯尔尼的汽车 + 火车行程”	road_multimodal_plan

---

交通工具的 API 密钥

1. 注册：https://api-manager.opentransportdata.swiss
2. 创建新应用 -> 订阅 "Strassenverkehr" API
3. 复制令牌

export OPENTRANSPORTDATA_API_KEY=<your-token>

如果没有密钥，交通工具会返回包含准确注册链接的说明性错误消息，不会导致程序崩溃。

---

架构

swiss_road_mobility_mcp/
├── server.py             # FastMCP server, 15 tools
├── api_infrastructure.py # Rate limiter, cache, HTTP client, geo utilities
├── shared_mobility.py    # sharedmobility.ch
├── ev_charging.py        # ich-tanke-strom.ch
├── traffic_situations.py # DATEX II traffic alerts (SOAP/XML)
├── traffic_counters.py   # DATEX II counting stations (SOAP/XML)
├── park_rail.py          # SBB Open Data Park & Rail
├── multimodal.py         # Snapshot + trip planner (cross-source)
└── geo_admin.py          # geo.admin.ch geocoding + road classification

数据源特征

来源	协议	覆盖范围	身份验证
sharedmobility.ch	REST/JSON (GBFS)	所有瑞士共享出行服务提供商	无
ich-tanke-strom.ch	GeoJSON	所有公共电动汽车充电桩	无
opentransportdata.swiss	DATEX II / SOAP+XML	ASTRA 交通数据	免费密钥
data.sbb.ch	REST/JSON (Opendatasoft)	SBB 停车换乘	无
transport.opendata.ch	REST/JSON	公共交通时刻表	无
geo.admin.ch	REST/JSON	官方地址、道路	无

深入文档： docs/ARCHITECTURE.md（MCP 原语、工具命名空间、用例目录、阶段路线图）· docs/SECURITY.md（凭据模型、出站流量允许列表、身份验证、 MCP 一致性表）· docs/OPERATIONS.md（资源限制、重启策略、运行状况）。

---

项目结构

swiss-road-mobility-mcp/
├── src/swiss_road_mobility_mcp/
│   ├── __init__.py              # Package
│   ├── server.py                # FastMCP server, 15 tools
│   ├── api_infrastructure.py    # Rate limiter, cache, HTTP client
│   ├── shared_mobility.py       # Shared vehicles
│   ├── ev_charging.py           # EV charging stations
│   ├── traffic_situations.py    # Traffic events
│   ├── traffic_counters.py      # Vehicle counting
│   ├── park_rail.py             # Park & Rail
│   ├── multimodal.py            # Snapshot + trip planning
│   └── geo_admin.py             # Geocoding + roads
├── tests/
│   ├── test_integration.py      # Live API tests
│   └── test_phase3.py           # Park & Rail + multimodal tests
├── .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

---

已知限制

• 共享出行： sharedmobility.ch API 不会严格执行半径过滤；可能会显示略微超出指定半径的车辆
• 电动汽车充电： 各运营商的站点命名惯例不一；部分站点可能没有详细名称
• 交通（DATEX II）： 需要免费的 API 密钥；如果没有密钥，交通工具会返回有帮助的错误消息
• 停车换乘： SBB 偶尔会重命名端点；服务端包含备用方案链
• 多式联运规划器： 响应时间取决于所查询数据源中最慢的一个

---

MCP 协议版本

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

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

协议时代取决于传输方式，而不只是请求。 本节早先曾写着“通过同一端点”，但这并不正确，而且当时无人发现：现代单次交换交付由 StreamableHTTPSessionManager 提供，只有 Streamable HTTP 应用才能访问。发布的传输方式是 SSE，而 SSE 需要会话；现代请求则从设计上就不需要会话。

MCP_TRANSPORT	端点	握手时代	2026-07-28
stdio（默认）	–	是	是
http	/mcp，以及并行提供的 /sse + /messages/	是	是
sse（旧版）	/sse + /messages/	是	否

MCP_TRANSPORT=http 支持两者：SSE 路由与 /mcp 并行运行，而不是被 /mcp 取代，因此服务端新增修订版本不会导致现有客户端出错。容器（Dockerfile、docker-compose.yml、render.yaml）使用 http。

这两个修订版本都固定在 tests/test_protocol_version.py 中，并与已安装的 SDK 进行断言，因此 Dependabot 升级 mcp 时不会悄然更改任一版本。由于该检查只能读取 SDK 常量，tests/test_spec_2026_07_28.py 也与其并列，用于测量实际传输内容：针对组装完成的 ASGI 应用发送真实的 2026-07-28 封装，并将相同封装发送到 SSE 作为对照。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——仅依据它进行固定，会让当前客户端实际协商的时代版本出现漂移。

更新策略。 检查失败时，不要盲目修改常量：先阅读两个修订版本之间的规范变更日志，确认服务端仍能正常工作，然后一并更新常量、本节、README.de.md 和 CHANGELOG.md。

---

测试

# All tests
pytest tests/ -v

# Quick check (without pytest)
python tests/test_phase3.py

---

安全与限制

• 只读： 所有工具仅执行 HTTP GET 请求——不会在任何上游系统中写入、修改或删除数据。
• 无个人数据： 作为工具输入传递的位置坐标不会被存储、记录或转发到即时 API 请求之外。API 响应不包含任何个人身份信息（PII），仅包含车辆数量、充电桩可用情况、交通事件和地理元数据。
• 速率限制： 服务端实施客户端速率限制（共享出行：30 次请求/60 秒；电动汽车充电：10 次请求/60 秒），以保护上游 API。DATEX II 密钥受 opentransportdata.swiss 合理使用条款约束。
• 缓存： 响应会在进程内缓存（共享出行：60 秒 · 电动汽车：5 分钟 · Park+Rail：5 分钟 · 交通：1–2 分钟）。实时数据反映的是缓存时长，不一定是当前时刻的数据。
• 服务条款： 数据受各上游来源的服务条款约束——sharedmobility.ch、ich-tanke-strom.ch、opentransportdata.swiss、data.sbb.ch（CC BY）、geo.admin.ch（BGDI）。
• 不作保证： 此服务是独立的社区项目，与 SBB、ASTRA、sharedmobility.ch 或任何 API 提供方均无关联。服务可用性取决于上游服务。

---

更新日志

参见 CHANGELOG.md

---

贡献

参见 CONTRIBUTING.md

---

安全

有关安全态势和漏洞报告，请参见 SECURITY.md。

---

许可证

MIT 许可证——参见 LICENSE

---

作者

Hayal Oezkan · malkreide

---

致谢与相关项目

• sharedmobility.ch： sharedmobility.ch — 瑞士共享出行平台
• ich-tanke-strom.ch： ich-tanke-strom.ch — 瑞士电动汽车充电网络
• ASTRA / opentransportdata.swiss： opentransportdata.swiss — 联邦交通数据
• SBB Open Data： data.sbb.ch — 瑞士联邦铁路
• geo.admin.ch： geo.admin.ch — 联邦地理空间服务
• 协议： Model Context Protocol — Anthropic / Linux Foundation
• 相关项目： swiss-transport-mcp — 公共交通（火车、公交车、有轨电车）
• 相关项目： zurich-opendata-mcp — 苏黎世市的 900 多个数据集
• 项目集： Swiss Public Data MCP Portfolio

安装

通过 uv 的 uvx 运行——无需克隆或手动安装。添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

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