🚇 Metro MCP

Model Context Protocol Server für US-Transitsysteme (DC Metro & NYC Subway)

Ein einheitlicher Remote-Model-Context-Protocol-Server (MCP), der mehrere US-Transitsysteme unterstützt. Derzeit werden die Washington DC Metro (WMATA) und die New York City Subway (MTA) unterstützt. Entwickelt für die nahtlose Integration mit MCP-kompatiblen Clients wie Claude Desktop, Cursor, Codex und jedem Client, der Streamable-HTTP-MCP-Server unterstützt.

Schnellzugriff: Schnellstart • Was du tun kannst • Transit Board • Bereitstellung • Client-Integration

Was du tun kannst

Stelle natürliche Sprachfragen zu DC Metro oder NYC Subway in Claude Desktop oder einem beliebigen MCP-kompatiblen Client:

🚆 Echtzeit-Transitinformationen

Washington DC:

• "Wann fährt der nächste Red Line Zug an der Dupont Circle?"

• "Welche Buslinien sind verfügbar?"

• "Finde Bushaltestellen in der Nähe von Dupont Circle"

• "Wo sind gerade alle 30N-Busse?"

• "Wann kommt der nächste Bus an der Haltestelle 1001195?"

• "Zeig mir alle Züge, die gerade im Metro-System unterwegs sind"

• "Gibt es gerade Verspätungen auf der Blue Line?"

• "Funktionieren alle Aufzüge an der Union Station?"

New York City:

• "Wann fährt der nächste 1-Zug am Times Square?"

• "Gibt es Verspätungen auf der A/C-Linie?"

• "Welche Züge kommen an der Grand Central an?"

• "Was ist der A-Zug und wohin fährt er?"

• "Welche nahegelegenen Stationen kann ich vom Times Square aus zu Fuß erreichen?"

• "Wie lange dauert es, zwischen den Bahnsteigen des Times Square zu laufen?"

🗺️ Stationsinformationen & Navigation

Washington DC:

• "Wo ist die Smithsonian Metro Station?"

• "Zeig mir alle Stationen auf der Green Line"

New York City:

• "Wo ist die Union Square Station?"

• "Zeig mir alle 496 Stationen der NYC Subway"

• "Welche Stationen verbinden mit dem Times Square?"

• "Erkläre den Unterschied zwischen Express- und Local-Zügen"

♿ Barrierefreiheit

Washington DC (Aufzugsausfälle):

• "Gibt es Aufzugsausfälle zwischen hier und dem National Airport?"

• "Welche DC Metro Stationen haben gerade funktionierende Aufzüge?"

🔔 Serviceüberwachung

Beide Städte:

• "Gibt es gerade Transitverspätungen in NYC?"

• "Läuft die DC Metro Orange Line normal?"

• "Vergleiche die Servicequalität zwischen DC Metro und NYC Subway"

📊 Systeminformationen

Washington DC:

• Vollständige Liste aller Metro-Stationen mit Koordinaten

• Informationen zu allen sechs Metro-Linien (Red, Blue, Orange, Silver, Green, Yellow)

New York City:

• Vollständige Abdeckung: Alle 496 NYC Subway Stationen mit Koordinaten

• Umstiegsinformationen: Gehzeiten zwischen verbundenen Stationen (87 Stationen mit Umstiegen)

• Routenbeschreibungen: Detaillierte Service-Muster für alle 29 Routen (Express vs. Local, Betriebszeiten)

• Bahnsteigklarheit: Erklärt Richtungsbahnsteige (z. B. „127N" = nordwärts am Times Square)

Related MCP server: marta-mcp

Schnellstart

Verwendung des öffentlichen Servers

Der schnellste Weg, loszulegen, ist die Verwendung der gehosteten Instanz:

1. Öffne deinen MCP-Client

2. Füge diese URL hinzu: https://metro-mcp.anuragd.me/mcp

3. Klicke auf „Verbinden" und autorisiere über GitHub

4. Beginne, Fragen zu DC Metro oder NYC Subway zu stellen

Eigene Instanz bereitstellen

Möchtest du deine eigene Instanz betreiben? Siehe den Abschnitt Bereitstellung unten.

Bereitstellung

Voraussetzungen

• WMATA-API-Schlüssel (erforderlich)

• Cloudflare-Konto (kostenlose Stufe funktioniert)

• Bun für die Paketverwaltung

• Node.js für Wrangler und den Workerd-Vitest-Pool; Bun bleibt der alleinige Paketmanager und Lockfile-Besitzer

• GitHub-OAuth-App (für die Authentifizierung)

Umgebungseinrichtung

Installiere genau das, was bun.lock aufzeichnet:

bun install --frozen-lockfile

Für die lokale Entwicklung erstelle eine dedizierte GitHub-OAuth-App, deren Callback exakt http://localhost:8787/callback ist. Kopiere dann die kanonische .dev.vars.example-Vorlage, ersetze jeden replace-with-...-Platzhalter und starte Wrangler:

cp .dev.vars.example .dev.vars
bun run dev

Behalte die http://localhost:8787-Origin der Vorlage, die localhost-Host/Origin-Allowlists, den Callback und die ENVIRONMENT=development-Werte zusammen. Im Standard-Lokalen Modus von Wrangler verwendet die konfigurierte OAUTH_KV-Bindung lokalen Nicht-Produktionsspeicher unter .wrangler; sie liest oder schreibt nicht den bereitgestellten Produktions- oder Preview-Namespace. Füge für normale lokale Entwicklung kein --remote hinzu.

Erstelle einen OAuth-Provider-Namespace für jede bereitgestellte Umgebung und setze seine ID in die entsprechende OAUTH_KV-Bindung:

bunx wrangler kv namespace create OAUTH_KV
bunx wrangler kv namespace create OAUTH_KV_preview

Produktion und Preview müssen ebenfalls unterschiedliche GitHub-OAuth-Apps verwenden. Konfiguriere jeden Callback als ${MCP_PUBLIC_ORIGIN}/callback; verwende niemals die Produktions-App oder OAuth-KV für Preview. Jede Umgebung setzt:

• MCP_PUBLIC_ORIGIN, MCP_ALLOWED_HOSTNAMES und MCP_ALLOWED_ORIGIN_HOSTNAMES

• OAUTH_REDIRECT_URI und die öffentliche GitHub-GITHUB_CLIENT_ID der Umgebung

• ENVIRONMENT (production, preview oder development)

• OAUTH_KV, das auf den dedizierten Namespace der Umgebung zeigt

Setze Produktionsgeheimnisse interaktiv. MCP_REQUEST_STATE_KEY ist ein stabiler, umgebungsspezifischer Schlüssel mit mindestens 32 Bytes, der nur für signierten MRTR-Zustand verwendet wird. JWT_SECRET bleibt vorübergehend für die Legacy-/mcp-Audience-Brücke bestehen.

bunx wrangler secret put MCP_REQUEST_STATE_KEY
bunx wrangler secret put GITHUB_CLIENT_SECRET
bunx wrangler secret put WMATA_API_KEY
bunx wrangler secret put JWT_SECRET

Setze dieselben vier Geheimnisnamen unabhängig für Preview; benannte Wrangler-Umgebungen erben keine Produktionsgeheimnisse:

bunx wrangler secret put MCP_REQUEST_STATE_KEY --env preview
bunx wrangler secret put GITHUB_CLIENT_SECRET --env preview
bunx wrangler secret put WMATA_API_KEY --env preview
bunx wrangler secret put JWT_SECRET --env preview

Wrangler muss sowohl nodejs_compat als auch global_fetch_strictly_public enthalten. Validiere beide Formen vor jeder genehmigten Bereitstellung:

bunx wrangler deploy --dry-run --outdir /tmp/metro-mcp-production
bunx wrangler deploy --dry-run --env preview --outdir /tmp/metro-mcp-preview

MCP-Client-Integration

Claude

Verwende den kanonischen Streamable-HTTP-Endpunkt in Claude Code:

claude mcp add --transport http metro-mcp https://metro-mcp.anuragd.me/mcp

Öffne dann /mcp, wähle metro-mcp und schließe den GitHub-Login und die Zustimmung ab. Claude.ai/Desktop-Benutzer können dieselbe URL als Remote-Custom-Connector hinzufügen, wo ihr Plan und ihre Workspace-Richtlinie dies zulassen.

Codex

codex mcp add metro-mcp --url https://metro-mcp.anuragd.me/mcp
codex mcp login metro-mcp --scopes transit:read

Die eingecheckte mcp-config.json zeigt die äquivalente generische Remote-HTTP-Konfiguration. Zugriffs- und Aktualisierungstokens bleiben im Credential-Store des Clients; füge sie nicht in die Projektkonfiguration ein.

Transportkompatibilität

• MCP-2026-07-28-Anfragen sind zustandslos und erfordern kein initialize.

• Gewöhnliche Tools, Ressourcen und Prompts bleiben für MCP-2025-zustandslose Clients verfügbar.

• POST /sse und OPTIONS /sse sind URL-Aliasse, die vor der Autorisierung auf kanonisches /mcp umgeschrieben werden.

• Legacy-HTTP+SSE ist entfernt. GET und DELETE auf /sse oder /mcp, Session-Message-URLs und /sse/ geben 405 zurück.

• OAuth-Audience und -Discovery verwenden immer https://metro-mcp.anuragd.me/mcp; /sse ist niemals eine OAuth-Ressource.

OAuth-Endpunkte

Der Workers-OAuth-Provider implementiert OAuth 2.1 mit PKCE:

• Discovery: /.well-known/oauth-authorization-server

• Registrierung: CIMD zuerst, mit /register als temporärem Fallback für Dynamic Client Registration

• Autorisierung: /authorize (GitHub-OAuth-Integration)

• Token: /token (Autorisierungscode-Austausch mit PKCE-Verifizierung)

• Callback: /callback (GitHub-OAuth-Callback)

Clients erhalten einen expliziten transit:read-Zustimmungsbildschirm. Gewährungen sind an die kanonische /mcp-Ressource gebunden; Zugriffstokens gelten höchstens 60 Minuten, Aktualisierungstokens höchstens 30 Tage und rotieren bei Verwendung, und Bearer-Tokens werden nur im Authorization-Header akzeptiert. Der DCR-Fallback läuft am 2027-06-30 aus.

Version 5.0 erfordert eine erneute Autorisierung für Tokens ohne Audience, Tokens, die an /sse gebunden sind, und Clients, die im alten DCR-Store registriert sind. Bestehende kompatible Legacy-JWTs, die an /mcp gebunden sind, funktionieren nicht mehr, sobald ihr eingebettetes Ablaufdatum oder 2026-11-30T00:00:00Z erreicht ist, je nachdem, was früher eintritt.

Unterstützte Städte

Der Server unterstützt derzeit diese Transitsysteme:

Verfügbare MCP-Tools

Der Server stellt die folgenden Tools über das MCP-Protokoll bereit:

Gesamt: 13 MCP-Tools (11 Kern-Tools + 2 neue NYC-spezifische Tools)

MCP-Apps: Transit Board

Alle 13 oben genannten Tools referenzieren eine eigenständige Transit-Board-MCP-App. Ein Apps-fähiger Host kann jedes Ergebnis als dedizierte Ankunfts-, Service-, Stations-/Netzwerk-, Routen- oder Fahrzeugansicht rendern. Hosts ohne Apps-Unterstützung erhalten denselben content-Text-Fallback und den structuredContent-Vertrag; die Erweiterung fügt keine Tools hinzu und ändert keine Transitaufrufe.

Die kompilierte App ist unter public/apps/transit-board.html eingecheckt. Dieses öffentliche Asset enthält nur Anwendungscode: kein Transitergebnis, keine Identität, kein Token, kein Geheimnis und kein Konfigurationswert ist darin eingebettet. Die Sandbox-Ansicht stellt keine direkten Browser-Netzwerkanfragen, verwendet keinen Browser-Speicher und fordert keine Browser-Berechtigungen an. Aktualisieren ist die einzige Serverinteraktion und erfolgt über den Host an das ursprüngliche Allowlist-Tool mit seinen ursprünglichen Argumenten.

Baue und führe die deterministische lokale Apps-Abnahmesuite aus mit:

bun run build:apps
bun run test:apps

Siehe docs/mcp-apps-verification.md für die genaue Host-Grenze, alle dreizehn Ansichtszuordnungen, Chromium-Abdeckung und die Unterscheidung zwischen Apps-Rendering und Fallback-Client-Abnahme. Für dieses Release validiert Codex MCP-Discovery und gewöhnliche Tool-Ergebnisse als Fallback-Client; Inline-Apps-Rendering in Codex wird nicht beansprucht.

Technische Details

MCP-Protokoll

• Version: MCP 2026-07-28, mit normaler zustandsloser Kompatibilität zu MCP 2025

• Transport: Zustandsloses Streamable HTTP über einen frischen SDK-v2-Server für jede Anfrage. JSON- und anfragebezogene SSE-Antworten werden unterstützt; Protokollsitzungen, Fortsetzbarkeit und Server-Push werden nicht beworben.

• Authentifizierung: Der Cloudflare Workers OAuth Provider besitzt Discovery, CIMD/DCR-Validierung, PKCE, RFC-9207-Ausstellerkennungen, RFC-8707-Ressourcenbindung, RFC-9728-Metadaten für geschützte Ressourcen, Refresh-Rotation, Widerruf und Provider-Token-Speicherung.

• Form der Tool-Ergebnisse: Jedes Tool gibt structuredContent (typisiertes Objekt, das outputSchema entspricht) zusammen mit dem veralteten content[0].text (serialisiertes JSON) für Abwärtskompatibilität aus.

• Tool-Anmerkungen: Jedes Tool deklariert readOnlyHint, idempotentHint, openWorldHint, damit Clients sichere Aktionsmöglichkeiten darstellen können.

• Verfügbare Fähigkeiten:

  • tools — 13 Transit-Abfrage-Tools (DC + NYC)

  • resources — drei transit://-URI-Vorlagen (Stationen, Routen, Vorfälle)

  • prompts — drei vorgefertigte Vorlagen (service-briefing, commute-planner, accessibility-check)

  • MRTR-Eingabe — moderne Clients erhalten input_required für mehrdeutige Stationen; MCP-2025-Clients erhalten deterministische Wiederholungsanleitungen mit exakten Stations-IDs

  • Fortschrittsbenachrichtigungen: werden für get_all_stations ausgegeben, wenn der Client über params._meta.progressToken zustimmt

Transit-APIs

WMATA (DC Metro):

Der Server greift auf die offiziellen WMATA-REST-APIs zu. Besuchen Sie WMATAs Entwicklerdokumentation für Details:

• Stationsvorhersagen: Echtzeit-Informationen zu Zugankünften

• Stationsinformationen: Stationsnamen, -codes und -standorte

• Vorfälle: Serviceunterbrechungen und Hinweise

• Aufzugs-/Rolltreppenausfälle: Informationen zur Barrierefreiheit

MTA (NYC Subway):

Der Server verwendet GTFS-Realtime-Feeds von der MTA. Öffentliche API-Endpunkte (kein API-Schlüssel erforderlich):

• Echtzeit-Feeds: Protocol-Buffers-Format mit 30-Sekunden-Aktualisierungsintervallen

• 8 separate Feeds: Abdeckung aller U-Bahn-Linien (1-7, A/C/E, B/D/F/M usw.)

• NYCT-Erweiterungen: Zug-IDs, Gleiszuweisungen und Richtungsinformationen

• Servicewarnungen: Eingebettet in GTFS-Realtime-Warnentitäten

Hosting

• Plattform: Cloudflare Workers

• Statische Assets: public/ wird über Cloudflare Workers Static Assets bereitgestellt und als env.ASSETS gebunden; der Worker bedient zuerst API-/OAuth-/MCP-Routen und delegiert dann Anfragen für Landingpage, Dokumentation, Bilder und Symbole an die Assets-Bindung.

• Speicher:

  • Umgebungsspezifisches Cloudflare KV OAUTH_KV — OAuth-Provider-Gewährungen, -Tokens und -Registrierungen

  • Keine aktive Speicherung von Protokollsitzungen. Der alte MetroMcpAgent-Export und die ursprüngliche v1-Migration bleiben nur für Rollback inaktiv.

• Laufzeit: V8-Isolate mit globaler Edge-Bereitstellung

Quellstruktur

Die Codebasis ist für die Unterstützung mehrerer Städte im Transitbereich mit einer klaren Trennung der Zuständigkeiten organisiert:

src/
├── index.ts              # Outer route normalization and Provider composition
├── public-handler.ts     # /info, OAuth UI, and static assets
├── route-normalizer.ts   # Exact /mcp admission and /sse URL alias
├── oauth/                # Provider configuration, GitHub consent, legacy bridge
├── mcp/                  # Stateless server factory, tools, resources, and prompts
├── mcp-agent.ts          # Inactive 4.x rollback class only
└── transit/              # WMATA and MTA clients with request cancellation

Wichtige Architekturentscheidungen:

• Transit-Abstraktion: Gemeinsame TransitAPIClient-Schnittstelle ermöglicht das einfache Hinzufügen neuer Städte (BART, MBTA usw.)

• Städte-Routing: Ein einzelner Server verarbeitet alle Städte über den city-Parameter in MCP-Tool-Aufrufen

• Normalisierte Antworten: Alle Transit-Clients geben standardisierte TransitStation-, TransitPrediction- und TransitIncident-Typen zurück

• Erweiterbarkeit: Das Hinzufügen einer neuen Stadt erfordert nur die Implementierung der abstrakten Client-Klasse

Verifizierung und Rollback

Führen Sie die vollständige lokale Suite mit bun run test aus. Der authentifizierte Konformitäts-Runner erfordert ein vom Betreiber beschafftes kurzlebiges Provider-Zugriffstoken in der Prozessumgebung; es speichert das Token nie und übergibt es nicht in Befehlsargumenten:

export MCP_CONFORMANCE_TARGET_URL=https://metro-mcp-preview.anuragd.me/mcp
export MCP_CONFORMANCE_ALLOW_REMOTE=1
read -rsp 'Short-lived MCP token: ' MCP_CONFORMANCE_TOKEN && export MCP_CONFORMANCE_TOKEN
./scripts/run-conformance.sh
unset MCP_CONFORMANCE_TOKEN

Siehe docs/mcp-2026-verification.md für den Kernprotokoll-Abnahmeprotokoll und docs/mcp-apps-verification.md für die Transit-Board-Browser-Grenze.

Rollback stellt die vorherige Worker-Version und ihre vorherigen Bindungen wieder her. Löschen Sie nicht den ursprünglichen MetroMcpAgent-Durable-Object-Namespace und fügen Sie während des Stabilisierungsfensters keine Löschmigration hinzu; Protokollsitzungszustand ist wegwerfbar, aber das Beibehalten der Klasse und der ursprünglichen v1-Migration ermöglicht weiterhin ein Rollback.

Ein Rollback von Transit Board entfernt die Apps-Metadaten/-Ressource, Browserquelle und Build-Abhängigkeiten, während Transit-Anbieter, OAuth, Routing, Bindungen und die Version unverändert bleiben.

Mitwirken

Beiträge sind willkommen! Sie können gerne:

• Melden Sie Fehler oder fordern Sie Funktionen über GitHub Issues an

• Reichen Sie Pull-Requests mit Verbesserungen ein

• Teilen Sie Feedback zur MCP-Implementierung

Lizenz

MIT-Lizenz – siehe LICENSE-Datei für Details.

Mit ❤️ für die Washington-DC-Metro-Community erstellt