japan-rail-mcp

japan-rail-mcp は、構造化された日本鉄道データを提供するための読み取り専用の Model Context Protocol（MCP）サーバーです。バージョン0.1は意図的に新幹線ファーストです。資格情報なしで利用できる便利な駅カタログを提供し、デプロイ所有者の Ekispert API Standard Plan キーを利用すれば、リアルタイムの新幹線時刻表、運賃、座席クラス、停車駅を照会できます。

このサーバーは、切符の予約、鉄道アカウントへのログイン、アクセス制御の回避、事業者Webサイトのスクレイピング、テストフィクスチャを実データとして提示することは一切行いません。

japan-rail-mcp は、china-rail-mcp と同じ概念インターフェースを共有するよう設計されており、長期的には、各国の鉄道MCPサーバー間で相互運用可能なスキーマを確立することを目指しています。

これは実験的な相互運用の取り決めであり、公式の鉄道規格やMCP標準ではありません。

機能

成功したすべてのデータには、情報出所のプロvenanceが含まれます。鉄道のタイムキーは日本のオフセット付きの明示的なISO 8601形式です。たとえば 2026-08-26T12:03:00+09:00 のようになります。「明日」などの相対日付はMCPクライアント側で解決する必要があります。サーバーは YYYY-MM-DD を要求します。

Related MCP server: DB Timetable MCP Server

MCPツール

すべてのツールは読み取り専用・非破壊・冪等であると明示されています。成功したすべてのツール結果には、人が読めるJSONテキストと、出力スキーマに照合したMCPの structuredContent の両方が含まれます。

インストール

要件: Node.js 22以上。CIはNode.js 24 LTSを使用しています。

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

stdioサーバーを起動します:

npm start

npmリリースした後は、クライアントが次の方法で起動することもできます:

npx -y japan-rail-mcp

ライブ新幹線データ

ライブの時刻表機能には、Ekispert APIの契約にStandard Planの経路検索エンドポイントが含まれるアクセスキーが必要です。無料プランでは、この中核エンドポイントは提供されません。

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

キーは、設定されたEkispert APIエンドポイントにのみ送信されます。ツール結果に返されたり、プロバイダーのエラーに含まれることはありません。このプロジェクトは、共有キーを含まず、プロバイダーデータのサブライセンスも行わず、契約に付随するリクエスト上限を上書きしません。

クライアント設定

Claude Desktop

ローカルチェックアウトでは、次のようなエントリを追加して絶対パスを置き換えてください:

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

駅名検索のみを行う場合は env オブジェクトを省略します。設定リポジトリにキーを保存するのではなく、クライアントのシークレット管理機能を使うことをお勧めします。

Codex

ビルド済みのstdioコマンドをCodexのMCP設定に登録するか、またはインストール済みのCodexバージョンがサポートするCLI形式を使用します:

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

ライブの列車データが必要な場合は、プロセス環境またはCodexのシークレット設定で EKISPERT_API_KEY を提供してください。

ツールの使用例

まずは駅の候補を解決します:

{
  "query": "Osaka"
}

この結果には、該当する場合に、大阪と新大阪の両方が意図的に含まれます。次に、その正確なIDを使います:

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

正規化された運賃は数値で、通貨安全:

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

formatted は表示専用です。比較には amount と currency を使用してください。

データソース

バンドル駅カタログ

プロジェクトが保守するカタログは、価値の高い58駅を収録しています。現在の新幹線ネットワークに加えて、大阪、新宿エリアの駅、富山の福岡駅など、意図的に曖昧な比較用駅を数を含んでいます。含まれるのは駅のメタデータのみで、時刻表・運賃・空席情報はありません。事業者による路線図や旅行ページへのリンクは、データソースの評価 にあります。

Ekispert API

この任意のプロバイダーは、文書化されたエンドポイントとデプロイ所有者のアクセスキーを使用します。明示的な日付、下限時刻が指定されていない場合は午前0時、停車駅、座席クラス、事業者詳細をリクエストします。レスポンスには、ekispert-standard、エンドポイントのデータセット、取得時刻、リアルタイムステータス、プロバイダー契約境界が含まれます。

新幹線時刻表データに使用されていないソース

• 現在の ODPT JR East の列車時刻表データセットは、新幹線を明示的に除外しています。

• GTFS-JP v4 はデータ仕様であり、全国的なフィードや包括的なデータライセンスではありません。

• JR の公開時刻表ページとPDFは、このプロジェクトに汎用APIや再配布許可を提供するものではないため、スクレイピングもバンドルもされません。

日付入りの評価と主なリンクは docs/data-sources.md を参照してください。

アーキテクチャ

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

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

MCPハンドラーはツール呼び出しを検証し記述しますが、プロバイダーのデータを取得・解析はしません。機能の確認は、ネットワークアクセス前にフェイルクローズ（引締した動作の安全側）を行います。search_trains は直通の物理列車を表し、search_journeys は乗り換えを含む旅程を表します。抽出境界については docs/architecture.md を参照してください。

china-rail-mcp との関係

共通のツール名は次のとおりです:

• search_stations

• search_trains

• get_train_details

• get_availability

• compare_trains

共通の候補スキーマは、Station、StationRef、Train、Journey、Fare、SeatClass、SeatAvailability、Source、RailError、RailProviderCapabilities です。この契約では、数値のISO 4217運賃、明示的な日本ローカル時刻のオフセット、出典、正規の駅ID、プロバイダー機能チェック、構造化エラーを維持します。

日本固有の詳細は extensions.japan にあり、以下を含みます:

• 新幹線の路線名とサービス名

• プロバイダーの駅名

• 旅客向けの列車番号と、運行上の識別子・プロバイダー識別子の比較

• 日本語の座席ラベル。例として、自由席、指定席、グリーン車、グランクラス

これらの境界は、将来のスタンドアローン rail-mcp-spec の候補です。本リポジトリは、そのような標準がすでに存在することを示すものではありません。

制限事項

• 資格情報が存在しないインストールは、駅検索のみを行います。

• ライブ列車の動作は、フィクスチャによる契約テストがありますが、このリポジトリ内では実アカウントで検証されていません。フィクスチャの成功は、本番環境のプロバイダーアクセスが証明されるものではありません。

• Ekispert Standard Planの内容、制限、表現の許可、商用利用、キャッシュ、再配布権利は、デプロイ所有者の契約に基づきます。

• 検索結果は、リクエストごとにプロバイダーが返す最初の20件に限定されます。

• search_trains は新幹線の直通運転のみを返します。乗り換えは静かに平らにしません。

• 座席クラスと公表運賃は、空席不是在庫ではありません。get_availability は対応していないままです。

• 運行の乱れやリアルタイムの列車位置は含まれません。

• バンドル駅カタログは新幹線中心であり、全国の完全な駅データベースではありません。

• 重要な旅程・運賃・乗車条件は、鉄道事業者または認可された予約チャネルで確認してください。

開発

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

テストでカバーしているのは、日本語/英語の駅名一致機能、曖昧さ、東京–新大阪のフィクスチャ解析、明示的な日付と東京タイムゾーンの境界、プロバイダーの障害、非対応の空席状況、MCP構造化出力、読み取り専用の注釈、Reusableの共有鉄道スキーマ契約です。

セキュリティと読み取り専用の範囲

チケット購入、予約、ログイン、決済、CAPTCHA、アカウント、データ操作を行うツールはありません。資格情報の取り扱い指針は SECURITY.md を参照してください。

ライセンス

プロジェクトのソースコードは MIT License の下で提供されています。このライセンスが適用されるのは、このリポジトリのソースコードのみであり、鉄道事業者のデータ、Ekispert のレスポンス、ODPTデータセット、GTFSフィード、各三者の商標を再配布権限を与えるものではありません。各データソースはそれぞれのユーザーの条件に従います。