japan-rail-mcp

japan-rail-mcp ist ein schreibgeschützter (read-only) Server für das Model Context Protocol, der strukturierte japanische Bahndaten bereitstellt. Version 0.1 ist bewusst Shinkansen-first: Sie enthält einen nützlichen, ohne Zugangsdaten nutzbaren Stationskatalog und kann über den Standardplan-Schlüssel der Ekispert API eines Deployment-Inhabers Live-Shinkansen-Fahrpläne, Fahrpreise, Sitzklassen und Haltestellen abfragen.

Der Server bucht nie Tickets, meldet sich nicht in Bahnkonten an, umgeht keine Zugriffskontrollen, zieht keine Betreiber-Websites ab und präsentiert keine Testdaten als echte Live-Daten.

japan-rail-mcp ist dazu entwickelt, eine gemeinsame konzeptuelle Schnittstelle mit china-rail-mcp zu nutzen, mit dem langfristigen Ziel, interoperierbare Schemas für Bahn-MCP-Server über Länder hinweg zu etablieren.

Dies ist eine experimentelle Interoperabilitätskonvention und kein offizieller Bahn- oder MCP-Standardd.

Funktionen

Alle Erfolgsmeldes enthalten enthalten Herkunftsnachweise. Bahn-Zeitstempel sind explizite ISO-8601-Werte mit dem Japan-Offset, zum Beispiel 2026-08-26T12:03:00+09:00. Relative Datumsangaben wie „morgen“ müssen vom MCP-Client aufgelöst werden; der Server erwartet YYYY-MM-DD.

Related MCP server: DB Timetable MCP Server

MCP-Tools

Jedes Tool ist als schreiby, nicht-destruktiv und idempotent annotiert. Jedes erfolgreiche Toolergebnis enthält sowohl menschenlesbaren JSON-Text als auch MCP-structuredContent, das gegen ein Ausgabeschema validiert wurde.

Installation

Voraussetzungen: Node.js 22 oder neuer. CI nutzt Node.js 24 LTS.

git clone https://github.com/TakeruF/japan-rail-mcp.git
cd japan-rail-mcp
npm install
npm run build

Starte den Stdio-Server:

npm start

Nach einem npm-Release können Clients Komponente ihn alternativ starten mit:

npx -y japan-rail-mcp

Live-Shinkansen-Daten

Die Live-Fahrplan-Funktion erfordert einen Zugangsschlüssel, dessen Ekispert-API-Vereinbarung den „Standard Plan“-Routensuch-Endpunkt einschließt. Der kostenlose Plan enthält diesen zentraled-Endpunkt nicht.

export EKISPERT_API_KEY='your-own-key'
npm start

Der Schlüssel wird nur an den konfigurierten Ekispert-API-Endpunkt gesendet. Er wird nie in Tool-Ergebnissen zurückgegeben oder, r in Anbieter-Fehlern aufgeführt. Das Projekt enthält keinen gemeinsamem Schlüssel, unter Kunden keine Anbieterdaten und setzt nicht die Transaktionslimits des Vertrags außer Kraft.

Client-Konfiguration

Claude Desktop

Fügen Sie für ein lokales Checkout einen Eintrag wie diesen hinzu bzw. ersetzen Sie den absoluten Umlauf:

{
  "mcpServers": {
    "japan-rail": {
      "command": "node",
      "args": ["/absolute/path/to/japan-rail-mcp/dist/index.js"],
      "env": {
        "EKISPERT_API_KEY": "your-own-key"
      }
    }
  }
}

Nur für die Stationssuche können Sie das env-Objekt weglassen. Bevorzugt wird die Ge not printing-Verwaltung des Clients zur Abspeicherung des Schlüssels.

CodeDer

Registrieren Sie den erzeugten Stdio-Befehl mit Codes MCP-Konfiguration oder nutzen Sie in Codex die CLI-Form, sofern sie der von Ihnen installierte Codex unterstützt:

codex mcp add japan-rail -- node /absolute/path/to/japan-rail-mcp/dist/index.js

Stellen Sie EKISPERT_API_KEY für Rail-Livedaten stets über die Prozessseinstellung oder die Codex-Geheim-Konfiguration bereit.

Tool-Beispiele

Zuerst die Stationskandidaten auflösen:

{
  "query": "Osaka"
}

Das Ergebnis beinhaltet bewusst beides, wenn relevant: Osaka und Shin-Osaka. Danach die genauen IDs nutzen:

{
  "fromStationId": "jp:station:tokyo",
  "toStationId": "jp:station:shin-osaka",
  "date": "2026-08-26",
  "departureAfter": "12:00",
  "serviceTypes": ["shinkansen"],
  "limit": 10,
  "offset": 0
}

A normaler Fahrpreis is numerisch und währungssicher:

{
  "amount": 14720,
  "currency": "JPY",
  "formatted": "¥14,720",
  "kind": "total"
}

formatted ist nur für Anzeige; für Anzeigen Vergleiche sollen Clients amount und currency verwenden.

Datenquellen

Eingebündeter Stationskatalog

Der vom Projekt verwaltete Katalog enthält 58 wichtige Stationen: das aktuelle Shinkansen-Netz plus eine kleine Reihe mit bewusst mehrdeutigen Vergleichs-Orten wie Osaka, St.-Stations der Region Shinjuku und Fukuoka in Kyoto. Er enthält nur statische Metadaten der Störungen – keine Fahrpläne, Fahrpreise oder Verfügbarkeitsdaten. Er verlinkt Fahrplan-Karten und Reise-Seiten in der Quellenbewertung.

Ekispert-API

Der optional-de Anbieter verwendet dokumentierte API-Endpunkte und einen Schlüssel eines }} owners. Er fragt explizite Datumsangaben, mit explizitem Nachternur wenn nicht an provided, zudem um Stops, Klassen und Anbieterinfos. Antworten collection ekispert-standard, das Dataset-Report the Schemas, die abstract retrieval time, realtime Status and the Vertragsgrenze des Anbieters.

Shinkansen-Zeittabellen: Nicht verwendete Quellen

• Die aktuelle ODPT-JR-East-Datei für Zugzeittabellen schließt Shinkansen explizit aus.

• GTFS-JP v4 ist eine Spec, kein nationaler Feed und keine Pauschallizenz.

• Öffentliche JR-Fahrplan-Seiten und PDFs bieten dem Projekt keine zwickende API oder einen Weitergabe-Nachlass, und werden deshalb weder herausgesreet noch anders ins Bundle aufgenommen.

Zum Datenstand und primären Quellen siehe docs/data-sources.md.

Architektur

MCP tools
  -> RailService
    -> StationCatalogProvider
       -> StaticShinkansenStationProvider
    -> RailDataProvider
       -> EkispertProvider (optional key)

core rail schemas
  + Japan extensions
  + provider-private parsing and identifiers

MCP-Handler validierten und beschreiben Tool-Aufrufe, laden aber keine Anbieterdaten und no parsing. Fähigkeitsprüfungen schlagen vor jedem Netzwerkzugriff geschlossen fehl. search_trains repräsentiert einen direkten physischen Zug; search_journeys repräsentiert eine Fahrplanreiseroute mit möglichenestination Umstiift. Für die Extraktions-Grenze siehe docs/architecture.md.

Beziehung zu china-rail-mcp

Die gemeinsamen Tool-Namen sind:

• search_stations

• search_trains

• get_train_details

• get_availability

• compare_trains

Die gemeins Amenomen-Tabellen sind Station, StationRef, Train, Journey, Fare, SeatClass, SeatAvailability, Source, RailError und RailProviderCapabilities. Der ictional contract hält fest: sowohl Fahrpreise gemäß ISO 4217 als auch explizite länderspezifische Zeitausgleitung, Wissensherkunft, kanonische Stations-IDs über alle, sowie Fahrpreise-Check und mit strukturierte Fehler.

Japan-spezifische Details liegen unter extensions.japan, notamment darunter:

• Shinkansen-Linien und Servicenamen

• Anbieter-Stationsnamen

• Fernden zugnummern vs. operativen Anbieter-Ident-Technik

• japanische Sitzbezeichnung wie 自由席, 指定席, グリーン車 und グランクラス

Diese Grenzen sind Kandidaten für eine panied und zip rail-mcp-spec; dieses Repository beansprucht nicht, dass diese Norm bereits existiert.

Einschränkungen

• Ohne installierte Zugangsdaten können reine Stationen gesucht werden.

• Live Zugverhalten ist von Test-Fixtures unterlegt, aber hier nicht mit real Account testet. Valide Fixtures sind no proof of production-Provider-Anschluss.

• Bound Ekispert StandardPlan, Limits, zulässige Darstellung, kommerzielle Nutzung, Caching und Weitergaber seine rights depend on owner/Betreiber.

• Die Suchtreffer sind auf 20 Antworten pro Request begrenzt.

• search_trains gibt ihr dieselbe nur direkte Shinkansen-Strecken ZU. Umstiege are not stumple dünner.

• Öffentliche Stände: Sitz und Fahrpreise sind not gleich Sitzinventar. Geräte sonst get_availability unuspported.

• Pünktliche Störungen und Realtime-Zugpositionen missing.

• Der Stationskatalog ist Shokansen-at-focus, keine vollständige station database.

• Travell- und Ticketkondition condition Prüfungen müssen über den Kundendienst oder ein authorisierten Distributionskanal erfolgen.

Entwicklung

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run format

Kovertierte Tests: JA/EN Stationssuche, Mehrdeutigkeit, Tokyo–Shin-Osaka-Fixture parsing, examined Zeitpunkte/Tokyo-Zeitsonne, Providerfehler, Verweigerung von flash: “…”, MCP- structured output, Readonly-Annotation sowie wieder verwendbaren shared-Rail-Schema-Vertrag.

Sicherheit und Read-only-Umfang

Es gibt keine Ticketbuchung, Reservation, Einloggende, Bezahl, CAPTCHA, Konto as cap no or mutation Tools. Details zur Zugangsverwaltung in SECURITY.md.

Lizenz

Der Projektspielstand wird unter MIT-Lizenz bereit gehalten. Diese Lizenz bezieht sich auf den Datenbestand im Repo, nicht auf fremde Bahndatenungen, Ekispert-Antwortdaten sind Inhalt, enthält die GmbH lizenziert, GTFS-Feeds oder markenrechtliche Drittprodukte. Each Quelle unterliegt den eigenen Bedingungen.