transitwalter

Selbst gehosteter MCP-Server für ÖPNV-Verbindungen weltweit – vom Flughafen zum Trailhead und zurück.

Daten kommen von Transitous (öffentliche MOTIS-API, offene Fahrplandaten aus vielen Ländern + OpenStreetMap). Keine Flüge – dafür gibt es eigene MCPs. Bahnpreise kommen über die (inoffizielle) Schnittstelle des DB Navigators – nicht nur für Deutschland, sondern auch für grenzüberschreitende und viele reine Auslandsstrecken. Läuft als Docker-Container mit Streamable-HTTP und Bearer-Token, z. B. auf einem Homeserver hinter einem Cloudflare-Tunnel.

Tools

Orte

Überall, wo ein Ort erwartet wird, geht:

• freier Text: Osnabrück Hbf, Purekkari neem, Ivinghoe Beacon

• Koordinaten: 59.67184,25.69492

• IATA-Code in Großbuchstaben: NCE, DTM, TLL – startet/endet an der Haltestelle am Terminal, nicht am Mittelpunkt des Flughafengeländes (von dort findet MOTIS oft keinen Fußweg, z. B. bei Nizza)

• eine ref aus transit_place_search / transit_airport (stop:…)

Zeiten sind Ortszeit des Start- (bzw. bei arrive_by des Ziel-)Orts, z. B. 2026-11-07T10:00. Ausgaben stehen in der Ortszeit der jeweiligen Haltestelle.

Verkehrsmittel

transport: all (Standard), regional (Nahverkehr ohne IC/ICE und Fernbusse – passend für Schwerbehindertenausweis oder Deutschlandticket), rail, no_rail. Sonderbusse mit eigenem Tarif (z. B. Flughafen-Expressbusse) erkennt der Filter nicht.

Fußwege

Standard ist ein zügiges Tempo (WALK_SPEED_KMH=5.5) und bis zu 30 min Fußweg zur ersten/von der letzten Haltestelle (MAX_WALK_MINUTES), damit lieber gelaufen als umgestiegen wird – z. B. Holzwickede Bahnhof → Dortmund Airport (18 min) statt AirportExpress. Beides pro Aufruf überschreibbar.

Karten und GPX liegen unter /x/<zufällige-id> (ohne Token erreichbar, 90 Tage): die Karte unter /x/<id>, alles als GPX unter /x/<id>.gpx, jeder Fußweg einzeln unter /x/<id>.w1.gpx, .w2.gpx … (mit Start und Ziel als Wegpunkten und sprechendem Dateinamen). Die GPX-Datei lässt sich in Komoot (Planen → GPX importieren), OsmAnd, Outdooractive usw. öffnen.

Warnungen

• Fahrplan noch nicht veröffentlicht: Liegt das Datum ≥ 5 Tage in der Zukunft, wird zusätzlich derselbe Wochentag in den nächsten Tagen abgefragt. Ist das Ergebnis dort deutlich besser, steht ein timetable_hint in der Antwort. Beispiel Estland: Elron-Züge sind nur wenige Tage im Voraus drin, sonst kommen 3–7 h Busfahrt statt 1 h Zug.

• Pro Verbindung (warnings): lange Wartezeiten, Übernachtungen, lange Fußwege, ausgefallene Fahrten, widersprüchliche Daten (Anschluss fährt vor der Ankunft ab).

Echtzeit

Wo die Verkehrsverbünde Echtzeitdaten an Transitous liefern (in Deutschland flächendeckend, in vielen anderen Ländern nicht), stehen in transit_journey_plan und transit_departures Verspätungen (delay_min) und Ausfälle (cancelled).

DB-Preise

transit_db_prices sucht selbst bei der DB (andere Ortssuche, andere Verbindungen als Transitous). Die DB verkauft auch viele Strecken im Ausland, im Test z. B. Wien → Venedig, Kopenhagen → Stockholm, Zürich → Mailand, Berlin → Prag; ohne Preis blieben u. a. Paris → Nizza, Tallinn → Tartu und Eurostar Amsterdam → Brüssel. Zeiten gelten als Ortszeit des Startbahnhofs. Die eigene BahnCard lässt sich mit DB_BAHNCARD als Standard setzen. price_from ist der günstigste Preis der Suche, meist ein Super Sparpreis mit Zugbindung; Verbund-Verbindungen ohne Preis in der Suche werden einzeln nachgefragt. deutschland_ticket=true rechnet Nahverkehrsabschnitte als bezahlt – passt auch für Schwerbehindertenausweis mit Wertmarke. Die Schnittstelle ist inoffiziell (db-vendo-client nutzt dieselbe), ohne Gewähr; die DB blockt manche Clients (z. B. curl, User-Agents mit URL) und drosselt schnell (DB_USER_AGENT, DB_REQUESTS_PER_MINUTE, Standard 10). Antworten werden 10 min gecacht.

Related MCP server: Transitous MCP Server

Fehlercodes

Tool-Fehler haben die Form CODE: Meldung, zusätzlich strukturiert als {"error": {"code": …, "message": …}}: INVALID_ARGUMENT, PLACE_NOT_FOUND, AIRPORT_NOT_FOUND, EXPORT_NOT_FOUND, RATE_LIMITED, CONFIG_ERROR, UPSTREAM_ERROR.

Transitous-Nutzungsregeln

Die öffentliche API ist für nicht-kommerzielle Projekte mit wenig Last gedacht (transitous.org/api): User-Agent mit Kontakt (TRANSITOUS_USER_AGENT), Ergebnisse cachen, ab ~720 Routenabfragen am Tag vorher Bescheid sagen, Quellen nennen (steht als attribution in jeder Antwort). transitwalter cacht Antworten (Orte 1 Tag, Verbindungen 10 min) und begrenzt sich auf 20 Anfragen pro Minute. Wer transitwalter in einem kommerziellen Zusammenhang nutzen will, sollte das vorher mit den Betreibern klären.

Lokal entwickeln

uv sync
cp .env.example .env               # MCP_TOKEN, TRANSITOUS_USER_AGENT eintragen
uv run python tests/unit.py        # Logik offline
uv run --env-file .env -- env PUBLIC_BASE_URL=http://localhost:8000 DATA_DIR=data transitwalter
uv run --env-file .env python tests/smoke.py   # zweites Terminal

Flughafendaten

src/transitwalter/data/airports.csv (≈4100 Flughäfen mit Linienverkehr) wird mit tools/build_airports.py aus OurAirports (gemeinfrei) erzeugt. Die Haltestellen am Terminal sucht transitwalter zur Laufzeit über Transitous.

Deployment

Siehe DEPLOY.md.