{
  "markdown": "> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide/swiss-public-data-mcp)**\n\n# 🚗 Swiss Road & Mobility MCP Server\n\n![Version](https://img.shields.io/badge/version-0.5.4-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)\n![CI](https://github.com/malkreide/swiss-road-mobility-mcp/actions/workflows/ci.yml/badge.svg)\n\n> MCP Server for Swiss road mobility — shared vehicles, EV charging, traffic alerts, Park & Rail, and multimodal trip planning\n\n[🇩🇪 Deutsche Version](README.de.md)\n\n---\n\n## Demo\n\n![Demo: Claude using road_mobility_snapshot at Zürich HB](docs/assets/demo.svg)\n\n---\n\n## Overview\n\n`swiss-road-mobility-mcp` provides AI-native access to Swiss road and mobility data sources:\n\n| Source | Data | API | Auth |\n|--------|------|-----|------|\n| **sharedmobility.ch** | Bikes, e-scooters, cars (GBFS) | REST/JSON | None |\n| **ich-tanke-strom.ch** | EV charging stations | GeoJSON | None |\n| **opentransportdata.swiss** | Traffic events, counting stations | DATEX II / SOAP+XML | Free key |\n| **data.sbb.ch** | Park & Rail facilities | REST/JSON (Opendatasoft) | None |\n| **transport.opendata.ch** | Public transport connections | REST/JSON | None |\n| **geo.admin.ch** | Address geocoding, road classification | REST/JSON | None |\n\nIf the Swiss Transport MCP is the GA pass for rail, this server is the vignette + Park & Rail card + sharing subscription for the road — together they paint the complete multimodal picture of Swiss mobility.\n\n**Anchor demo query:** *\"I'm in Dietikon with my car. I need to get to Bern. Where can I park? Which train should I take?\"*\n\n---\n\n## Features\n\n- **15 tools** across six data sources (Phase 1–4)\n- **`road_mobility_snapshot`** — aggregated mobility overview for any location\n- **`road_multimodal_plan`** — car + Park & Rail + public transport in one plan\n- No API key required for 12 of 15 tools\n- Dual transport — stdio (Claude Desktop) + SSE (cloud)\n- Rate limiting + caching for all endpoints\n\n---\n\n## Prerequisites\n\n- Python 3.11+\n- [uv](https://github.com/astral-sh/uv) (recommended) or pip\n\n---\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/malkreide/swiss-road-mobility-mcp.git\ncd swiss-road-mobility-mcp\n\n# Install\npip install -e .\n# or with uv:\nuv pip install -e .\n```\n\nOr with `uvx` (no permanent installation):\n\n```bash\nuvx swiss-road-mobility-mcp\n```\n\n---\n\n## Quickstart\n\n```bash\n# stdio (for Claude Desktop)\nswiss-road-mobility-mcp\n# or:\npython -m swiss_road_mobility_mcp.server\n\n# SSE (for cloud / Render.com)\nMCP_TRANSPORT=sse MCP_PORT=8001 swiss-road-mobility-mcp\n```\n\nTry it immediately in Claude Desktop:\n\n> *\"Show me everything mobility-related at Zurich HB.\"*\n> *\"Find shared bikes near Bern Bahnhof.\"*\n> *\"Where can I charge my EV near Lucerne?\"*\n\n→ [More use cases by audience](EXAMPLES.md) →\n\n---\n\n## Configuration\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-road-mobility\": {\n      \"command\": \"uvx\",\n      \"args\": [\"swiss-road-mobility-mcp\"],\n      \"env\": {\n        \"OPENTRANSPORTDATA_API_KEY\": \"<your-token>\"\n      }\n    }\n  }\n}\n```\n\nOr with `python`:\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-road-mobility\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"swiss_road_mobility_mcp.server\"],\n      \"env\": {\n        \"OPENTRANSPORTDATA_API_KEY\": \"<your-token>\"\n      }\n    }\n  }\n}\n```\n\n> Shared mobility, EV charging, Park & Rail, and the multimodal planner work **without** an `OPENTRANSPORTDATA_API_KEY`. The key is only required for the DATEX II traffic tools.\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Cloud Deployment (SSE for browser access)\n\nFor use via **claude.ai in the browser** (e.g. on managed workstations without local software):\n\n**Render.com (recommended):**\n1. Push/fork the repository to GitHub\n2. On [render.com](https://render.com): New Web Service -> connect GitHub repo\n3. Set start command: `MCP_TRANSPORT=sse MCP_PORT=8001 swiss-road-mobility-mcp`\n4. In claude.ai under Settings -> MCP Servers, add: `https://your-app.onrender.com/sse`\n\n#### SSE security (SEC-009)\n\nA public SSE endpoint is reachable by anyone. To protect it (and your upstream\nAPI quota), configure these environment variables on the host:\n\n| Variable | Effect |\n|---|---|\n| `MCP_AUTH_TOKEN` | When set, every SSE request must send `Authorization: Bearer <token>`. **Unset = unauthenticated** (the server logs a loud warning at startup). Strongly recommended for any public deployment. |\n| `MCP_RATE_LIMIT` | Max requests per client IP per window (default `60`, `0` disables). |\n| `MCP_RATE_WINDOW` | Window length in seconds (default `60`). |\n| `ALLOWED_ORIGINS` | Comma-separated CORS origins for browser clients. **Empty by default: no cross-origin access.** `*` allows any origin and is logged as a warning. Does not affect stdio or other non-browser clients. |\n\nThe local **stdio** transport needs none of this — it runs in the user's\ntrusted context.\n\n#### Observability (OBS-003 / OBS-006)\n\n| Variable | Effect |\n|---|---|\n| `MCP_LOG_LEVEL` | Log level: `DEBUG` / `INFO` (default) / `WARNING` / `ERROR`. |\n| `MCP_LOG_FORMAT` | `text` (default) or `json` for structured logs. All logs go to **stderr**. |\n| `MCP_TRACING_ENABLED` | `true` enables OpenTelemetry tracing (off by default). |\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector URL; setting it also enables tracing. Standard `OTEL_*` vars are honoured by the SDK. |\n\nTracing needs the optional extra: `pip install 'swiss-road-mobility-mcp[tracing]'`.\nOnce enabled, every upstream API call is traced automatically (httpx\ninstrumentation) and SSE requests get server spans with W3C trace-context\npropagation.\n\n---\n\n## Available Tools\n\n### Shared Mobility & EV Charging (no API key required)\n\n| Tool | Description | Cache |\n|------|-------------|-------|\n| `road_find_sharing` | Shared mobility nearby (bikes, e-scooters, cars) | 60s |\n| `road_search_sharing` | Search sharing stations by name | 5min |\n| `road_sharing_providers` | All sharing providers in Switzerland | 1h |\n| `road_find_charger` | EV charging stations nearby | 5min |\n| `road_charger_status` | Real-time availability of charging stations | 1min |\n| `road_check_status` | Server & API health check | - |\n\n### Traffic (free API key required)\n\n| Tool | Description | Cache |\n|------|-------------|-------|\n| `road_traffic_situations` | Accidents, roadworks, congestion from ASTRA/VMZ-CH | 2min |\n| `road_traffic_counters` | Vehicles/h + km/h at counting stations near a position | 1min |\n| `road_counter_sites` | List counting stations nearby | 24h |\n\n### Park & Rail + Multimodal (no API key required)\n\n| Tool | Description | Cache |\n|------|-------------|-------|\n| `road_park_rail` | Find SBB Park+Rail facilities nearby | 5min |\n| `road_mobility_snapshot` | Complete mobility overview for a location | - |\n| `road_multimodal_plan` | Plan car -> Park+Rail -> public transport -> destination | - |\n\n### Geography & Addresses — Phase 4 (no API key required)\n\n| Tool | Description | Cache |\n|------|-------------|-------|\n| `road_geocode_address` | Swiss address -> GPS (official building address register) | - |\n| `road_reverse_geocode` | GPS -> official address with EGID/EGAID (GWR) | - |\n| `road_classify_road` | Road classification via swissTLM3D | - |\n\n### Example Use Cases\n\n| Query | Tool |\n|-------|------|\n| *\"Find shared bikes near Zurich HB\"* | `road_find_sharing` |\n| *\"Where can I charge my EV near Bern?\"* | `road_find_charger` |\n| *\"Any traffic incidents on the A1?\"* | `road_traffic_situations` |\n| *\"Where can I park near Winterthur station?\"* | `road_park_rail` |\n| *\"Plan my trip from Dietikon to Bern by car + train\"* | `road_multimodal_plan` |\n\n---\n\n## API Key for Traffic Tools\n\n1. Register: <https://api-manager.opentransportdata.swiss>\n2. Create a new application -> subscribe to the \"Strassenverkehr\" API\n3. Copy the token\n\n```bash\nexport OPENTRANSPORTDATA_API_KEY=<your-token>\n```\n\nWithout a key, the traffic tools return a descriptive error message including the exact registration link — no crash.\n\n---\n\n## Architecture\n\n```\nswiss_road_mobility_mcp/\n├── server.py             # FastMCP server, 15 tools\n├── api_infrastructure.py # Rate limiter, cache, HTTP client, geo utilities\n├── shared_mobility.py    # sharedmobility.ch\n├── ev_charging.py        # ich-tanke-strom.ch\n├── traffic_situations.py # DATEX II traffic alerts (SOAP/XML)\n├── traffic_counters.py   # DATEX II counting stations (SOAP/XML)\n├── park_rail.py          # SBB Open Data Park & Rail\n├── multimodal.py         # Snapshot + trip planner (cross-source)\n└── geo_admin.py          # geo.admin.ch geocoding + road classification\n```\n\n### Data Source Characteristics\n\n| Source | Protocol | Coverage | Auth |\n|--------|----------|----------|------|\n| sharedmobility.ch | REST/JSON (GBFS) | All CH sharing providers | None |\n| ich-tanke-strom.ch | GeoJSON | All public EV chargers | None |\n| opentransportdata.swiss | DATEX II / SOAP+XML | ASTRA traffic data | Free key |\n| data.sbb.ch | REST/JSON (Opendatasoft) | SBB Park & Rail | None |\n| transport.opendata.ch | REST/JSON | Public transport schedules | None |\n| geo.admin.ch | REST/JSON | Official addresses, roads | None |\n\n**In-depth docs:** [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) (MCP primitives,\ntool namespacing, use-case catalogue, phase roadmap) ·\n[`docs/SECURITY.md`](docs/SECURITY.md) (credential model, egress allow-list, auth,\nMCP conformance table) ·\n[`docs/OPERATIONS.md`](docs/OPERATIONS.md) (resource limits, restart policy, health).\n\n---\n\n## Project Structure\n\n```\nswiss-road-mobility-mcp/\n├── src/swiss_road_mobility_mcp/\n│   ├── __init__.py              # Package\n│   ├── server.py                # FastMCP server, 15 tools\n│   ├── api_infrastructure.py    # Rate limiter, cache, HTTP client\n│   ├── shared_mobility.py       # Shared vehicles\n│   ├── ev_charging.py           # EV charging stations\n│   ├── traffic_situations.py    # Traffic events\n│   ├── traffic_counters.py      # Vehicle counting\n│   ├── park_rail.py             # Park & Rail\n│   ├── multimodal.py            # Snapshot + trip planning\n│   └── geo_admin.py             # Geocoding + roads\n├── tests/\n│   ├── test_integration.py      # Live API tests\n│   └── test_phase3.py           # Park & Rail + multimodal tests\n├── .github/workflows/ci.yml     # GitHub Actions (Python 3.11/3.12/3.13)\n├── pyproject.toml\n├── CHANGELOG.md\n├── CONTRIBUTING.md               # Contribution guide (English)\n├── CONTRIBUTING.de.md            # Contribution guide (German)\n├── SECURITY.md                   # Security policy (English)\n├── SECURITY.de.md                # Security policy (German)\n├── LICENSE\n├── README.md                    # This file (English)\n└── README.de.md                 # German version\n```\n\n---\n\n## Known Limitations\n\n- **Shared Mobility:** The `sharedmobility.ch` API does not enforce strict radius filtering; vehicles slightly outside the specified radius may appear\n- **EV Charging:** Station naming conventions vary between operators; some stations may appear without detailed names\n- **Traffic (DATEX II):** Requires a free API key; without it, traffic tools return helpful error messages\n- **Park & Rail:** SBB occasionally renames endpoints; the server includes a fallback chain\n- **Multimodal Planner:** Response time depends on the slowest of the queried sources\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `initialize` handshake | `2024-11-05` … **`2025-11-25`** | What today's clients speak. The server answers with the revision asked for, or with the `2025-11-25` ceiling when the request asks for something newer. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. This server builds no ASGI app to send an `initialize` through, so\nthe gate asserts the SDK constants rather than a measured response — the\nweaker form, named rather than left unsaid.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n---\n\n## Testing\n\n```bash\n# All tests\npytest tests/ -v\n\n# Quick check (without pytest)\npython tests/test_phase3.py\n```\n\n---\n\n## Safety & Limits\n\n- **Read-only:** All tools perform HTTP GET requests only — no data is written, modified, or deleted on any upstream system.\n- **No personal data:** Location coordinates passed as tool inputs are not stored, logged, or forwarded beyond the immediate API request. API responses contain no PII — only vehicle counts, charger availability, traffic events, and geographic metadata.\n- **Rate limiting:** The server enforces client-side rate limits (Shared Mobility: 30 req/60s; EV Charging: 10 req/60s) to protect upstream APIs. The DATEX II key is subject to opentransportdata.swiss fair-use terms.\n- **Caching:** Responses are cached in-process (Sharing: 60s · EV: 5 min · Park+Rail: 5 min · Traffic: 1–2 min). Real-time data reflects the cache age, not necessarily the current second.\n- **Terms of service:** Data is subject to the ToS of each upstream source — [sharedmobility.ch](https://sharedmobility.ch), [ich-tanke-strom.ch](https://ich-tanke-strom.ch), [opentransportdata.swiss](https://opentransportdata.swiss), [data.sbb.ch](https://data.sbb.ch) (CC BY), [geo.admin.ch](https://www.geo.admin.ch/de/geo-dienstleistungen/geodienste/terms-of-use.html) (BGDI).\n- **No guarantees:** This server is an independent community project, not affiliated with SBB, ASTRA, sharedmobility.ch, or any API provider. Availability depends on upstream services.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for the security posture and vulnerability reporting.\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE)\n\n---\n\n## Author\n\nHayal Oezkan · [malkreide](https://github.com/malkreide)\n\n---\n\n## Credits & Related Projects\n\n- **sharedmobility.ch:** [sharedmobility.ch](https://sharedmobility.ch/) — Swiss shared mobility platform\n- **ich-tanke-strom.ch:** [ich-tanke-strom.ch](https://ich-tanke-strom.ch/) — Swiss EV charging network\n- **ASTRA / opentransportdata.swiss:** [opentransportdata.swiss](https://opentransportdata.swiss/) — Federal traffic data\n- **SBB Open Data:** [data.sbb.ch](https://data.sbb.ch/) — Swiss Federal Railways\n- **geo.admin.ch:** [geo.admin.ch](https://api3.geo.admin.ch/) — Federal geospatial services\n- **Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) — Anthropic / Linux Foundation\n- **Related:** [swiss-transport-mcp](https://github.com/malkreide/swiss-transport-mcp) — Public transport (trains, buses, trams)\n- **Related:** [zurich-opendata-mcp](https://github.com/malkreide/zurich-opendata-mcp) — 900+ datasets from the City of Zurich\n- **Portfolio:** [Swiss Public Data MCP Portfolio](https://github.com/malkreide/swiss-public-data-mcp)\n\n<!-- mcp-name: io.github.malkreide/swiss-road-mobility-mcp -->\n\n<!-- BEGIN GENERATED: install -->\n## Installation\n\nRun via [`uv`](https://docs.astral.sh/uv/)'s `uvx` — no clone or manual install needed. Add to your MCP client config (`mcpServers` for Claude Desktop, Cursor and Windsurf; use a top-level `servers` key for VS Code in `.vscode/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swiss-road-mobility-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"swiss-road-mobility-mcp\"\n      ]\n    }\n  }\n}\n```\n<!-- END GENERATED: install -->\n",
  "bytes": 16693,
  "sha": "0f2f26217ca576f19d35682572c6c0639ef17b95c5b5c82d797d7932012082cf",
  "repo_slug": "malkreide/swiss-road-mobility-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_swiss_road_mobility__c8cd1e94/readme"
}