🌐 Language / 言語 / 语言: 日本語 | English | 中文

🚃 Tokyo Transit MCP Server

ODPT API + 気象庁 API を統合した東京圏総合交通情報MCPサーバー

鉄道・モノレール・AGT・路面電車・水上バス・フェリー・バス・シェアサイクルまで、東京圏の移動手段を1つのMCPサーバーで横断検索できます。天候や運行情報を加味した AI インテリジェントアドバイスを、日本語・英語・中国語で自動生成します。

✨ 特徴

路線検索に加えて、気象データや交通オープンデータ（ODPT / GBFS / GTFS）を統合し、リアルタイムの移動アドバイスを提供する高度なMCPサーバーです。主な特徴は次のとおりです。

🚉 全交通機関を統合

計124路線・1,430駅を網羅（経路探索はAPIキー不要の内蔵グラフで動作）：

🛤️ 直近の更新内容

• コード監査で発見した交通API障害・曖昧検索・キャッシュの不都合を修正（v2.42.1）

  • 時刻表API障害の誤判定を修正: ODPTの路線一覧取得失敗を NO_DATA として返さず、サーキットブレーカーへ通知してAPIエラーとして扱うよう改善

  • バス停の曖昧検索を停止: 複数事業者・地域の候補が一致した場合、先頭候補を自動採用せず AMBIGUOUS_BUS_STOP と候補一覧を返すよう変更

  • キャッシュを真のLRU化: 参照されたエントリを最新として扱い、容量超過時の不要な再取得を抑制

  • APIエラー分類を細分化: 認証失敗（401/403）、サーバー障害（5xx）、タイムアウト、内部エラーを区別して構造化レスポンスに反映

  • 検証 — 全対象モジュール node --check、修正回帰テスト、実データによるルート・バス停・時刻表スモークテスト、git diff --check が PASS

🤖 AI インテリジェントアドバイス

天候や運行情報から、移動に役立つ具体的なアドバイスを自動生成します。

• ☀ 晴天時 — 快適な移動をサポート

• ☔ 雨天時 — 濡れた駅構内・階段の滑りやすさを注意喚起し、バス振替を推奨

• 🌡 高温時 — 熱中症警戒アラートと水分補給を推奨

• ❄ 降雪時 — 足元の凍結・遅延・運休の可能性を案内し、時間に余裕を持つ移動を推奨

• 🚨 緊急時 — 運転見合わせ・災害検知時は避難所リンクを自動表示

🛡 セーフティ＆フォールトトレランス

• サーキットブレイカー — 3回連続失敗で60秒クールダウン（段階的に延長）

• 統一キャッシュ管理 — API負荷を最大80%削減（最長24時間キャッシュ）

• デグレードモード — API障害時も部分稼働を継続

• 荒天時安全ロジック — 台風・浸水時は自転車案内を自動非表示

• LLMフレンドリーJSON — 全エラーを、AIが状況・再試行可否・次の選択肢を解釈しやすい構造化データで出力

💬 自然言語で簡単検索

駅名・バス停・港名・ランドマーク名は、部分一致・表記揺れ・略称・旧称・多言語名を含む自然な表現から自動解決します。鉄道だけでなく、バス・コミュニティバス・フェリー・水上バス・空港アクセスをまたぐ複数交通モードの横断検索にも対応しています。出発地と到着地を「から」「まで」「to」「from ... to ...」「从 ... 到 ...」などで結んで、そのまま入力できます。

検索例（日本語・英語・中国語）:

1. 略称・通称から検索（日本語）

   スカイツリーから浅草まで

2. 旧称・表記揺れを含むランドマーク検索（日本語）

   雷門から東京ビッグサイトまでの経路

3. ランドマーク名から最寄り駅を自動解決（日本語）

   成田山新勝寺から新宿へ行きたい

4. 鉄道＋バスの横断検索（日本語）

   東京ビッグサイトまでバスと電車で行くルート

5. 駅名の英語表記・観光地名から検索（英語）

   Shibuya to Odaiba route

6. 空港アクセスを含む複数モード検索（英語）

   Find a route from Haneda Airport to Narita Airport

7. 港名・フェリーを含む検索（英語）

   Ferry route from Tokyo Takeshiba Pier to Oshima

8. 中国語の自然文によるランドマーク検索（中国語）

   查询从浅草寺到东京晴空塔的路线

9. 中国語の鉄道＋バス横断検索（中国語）

   请查询从东京站到东京迪士尼乐园的电车和巴士换乘

10. 略称・英語名・旧名を組み合わせた検索（英語）

    How do I get from HND to Tokyo Skytree, including the last-mile option?

駅・バス停・港・ランドマークの候補が複数ある場合は、誤った地点を推測せず候補を提示して選択を求めます。ランドマーク入力時は最寄り駅を案内し、到着地点周辺では通常時にレンタサイクル情報も表示します。荒天・降雪・凍結時は安全のため自転車案内を表示しません。

⚠️ ご注意: 本サーバーは MCP クライアント（Claude Desktop / Hermes 等）上の LLM モデルを介して応答を表示します。モデルにより、AIインテリジェントアドバイスや検索結果の表示揺れ（表現の違い・省略の有無等）が若干発生する場合があります。検索エンジン自体のJSON出力はモデルに依存せず一定ですが、最終的な文章化はモデルに左右されます。

🌐 マルチランゲージ

利用者の質問言語に合わせて、応答全体を日本語・英語・中国語でローカライズします。AIアドバイスだけでなく、経路の駅名・路線名、天気テキスト、エラーメッセージも同じ言語で返します。

通常は質問文から自動判定します。駅名が日本語表記でも、英語・中国語で質問された場合は language: "en" / language: "zh" を指定すると、確実に希望言語で応答します。

🔧 テストモード（-test）

search_route に -test <障害種別> を付けると、20種類以上の障害シミュレーションが可能です。詳細は「障害シミュレーション」セクションを参照してください。

Related MCP server: Tokyo WBGT MCP Server

📦 セットアップ

リポジトリのクローン、依存関係のインストール、MCPクライアント（Claude Desktop / Hermes 等）への設定追加の順に進めます。

# リポジトリをクローン
git clone https://github.com/loosephoto/tokyo-transit-mcp.git
cd tokyo-transit-mcp

# 依存関係インストール
npm install

# ODPT API キーを設定（https://developer.odpt.org/ から取得）
echo 'ODPT_API_KEY=your_api_key_here' > .env
# フライト時刻を利用する場合のみ設定（AviationStack APIキー・任意: https://aviationstack.com/）
echo 'FLIGHT_API_KEY=your_flight_api_key_here' >> .env

MCP クライアント設定例（Claude Desktop / Hermes 等）

APIキーはMCPクライアントの設定ファイルには記載せず、リポジトリルートの .env のみに保存します。サーバーは src/config.mjs の位置を基準に .env を読み込むため、MCPクライアントの起動時カレントディレクトリには依存しません。

{
  "mcpServers": {
    "tokyo-transit": {
      "command": "node",
      "args": ["/path/to/tokyo-transit-mcp/src/index.mjs"]
    }
  }
}

/path/to/tokyo-transit-mcp/.env に以下を設定してください。

ODPT_API_KEY=your_api_key_here
FLIGHT_API_KEY=your_flight_api_key_here

.env は秘密情報を含むため、共有・コミットしないでください。

🛠 使用可能ツール

本MCPサーバーは12種類のツールを提供します。概要は早見表、詳細は各セクションを参照してください。

1. search_route — 乗換ルート検索（メイン機能）

機能: 出発駅→到着駅のルートを検索し、天気・運行情報を自動取得して AI アドバイスを付加します。入力言語（日/英/中）に応じて応答全体（駅名・路線名・天気・エラー）を自動ローカライズします。

search_route(from: "渋谷", to: "新宿")

パラメータ:

• from (string) — 出発駅名（または最寄り駅に変換可能な施設名・ランドマーク名）

• to (string) — 到着駅名（または最寄り駅に変換可能な施設名・ランドマーク名）

• language (string, 任意) — 応答言語の強制指定 ja / en / zh。省略時は駅名から自動判定しますが、ユーザーのクエリ言語に合わせて指定すると確実にその言語で応答します（例: 英語で質問したのに駅名が日本語の場合に language: "en" を渡すと英語で返答）

入力例:

search_route(from: "東京", to: "サンリオピューロランド")
search_route(from: "Tokyo", to: "Mori Art Museum", language: "en")
search_route(from: "东京", to: "三丽鸥彩虹乐园", language: "zh")
search_route(from: "Shibuya", to: "Yoyogi Park", language: "en")
search_route(from: "涩谷", to: "代代木公园", language: "zh")

• user_location (object, 任意) — 利用者の現在位置 { lat: number, lon: number }。指定時は運転見合わせ時のシェアサイクル案内を現在地基準で表示（未指定時は出発駅基準）

レスポンス例:

{
  "status": "SUCCESS",
  "from": "渋谷",
  "to": "新宿",
  "weather_text": "東京地方: 晴れ",
  "direct_search_url": "https://transit.yahoo.co.jp/...",
  "ai_transit_advice": "🤖 【AIからのインテリジェントアドバイス】\n晴れの良好なお天気です！...",
  "community_bus_access": [{ "station": "渋谷", "buses": [{ "bus": "ハチ公バス", "stop": "渋谷駅東口" }] }],
  "gov_facility_search_support": { "...": "..." },
  "station_bus_stops": { "...": "..." },
  "fare_available": true
}

テストモード（障害シミュレーションの詳細は下記セクション参照）:

search_route(from: "東京 -test 人身事故", to: "新宿")
search_route(from: "新宿 -test 台風", to: "渋谷")
search_route(from: "Tokyo -test typhoon", to: "Shinjuku")
search_route(from: "东京 -test 台风", to: "新宿")

2. get_station_info — 駅情報取得

指定した駅の基本情報（乗り入れ路線・事業者等）を取得します。

get_station_info(station_name: "渋谷", operator: "tokyometro")

3. get_weather — 天気情報

気象庁APIから天気・気温を取得します。高温時は熱中症注意を表示します。

get_weather(area_name: "東京")

4. search_fare — 運賃検索

2駅間の運賃をODPTデータから検索します（東京メトロ・都営・横浜市営地下鉄・つくばエクスプレス・りんかい線・ゆりかもめ・多摩モノレール対応）。

search_fare(from: "渋谷", to: "新宿")

{
  "fares": [{ "operator": "TokyoMetro", "ticket": 200, "ic": 198 }]
}

5. get_timetable — 時刻表検索

指定駅の時刻表をODPTデータから検索します。

get_timetable(station_name: "渋谷", railway: "山手線")

6. search_bus — バス路線・乗り継ぎ検索

search_bus(busstop_name: "渋谷駅前")
search_bus(from: "渋谷駅前", to: "新橋駅前")
search_bus(from: "浅草", to: "上野", vehicle: "bus")

開発・回帰検証

コード変更後は、構文チェックと多言語回帰プローブを実行します。npm test は検索結果だけでなく、weather_text、nearby_suggestions、駅名・路線名などの補助表示も検査します。

npm run build       # node --check src/index.mjs
npm test            # 全26ケースの日本語・英語・中国語回帰
npm run test:walk   # 近接異名駅（徒歩連絡）・同名別駅・路線データ整合性の回帰
npm run test:bus    # バス乗り継ぎ実APIプローブ（API状況により長時間化）
npm run test:vehicle # vehicle優先の決定的モック回帰

npm test の終了コードをCIの品質ゲートに使用できます。実APIを使うバス乗り継ぎプローブがタイムアウトしても、決定的なモック回帰とは別に評価してください。

7. search_flight — 空港フライト時刻・到着時刻表示

search_flight(airport: "羽田空港", direction: "arrival")
search_flight(airport: "成田空港", direction: "arrival", destination: "東京駅")
search_flight(flight_number: "NH001", direction: "arrival")

8. list_transit_operators — 交通事業者一覧

全事業者（鉄道・AGT・モノレール・路面電車・フェリー）を種別フィルタ付きで表示します。

list_transit_operators(language: "ja", type_filter: "all")

9. get_operator_routes — 事業者別路線一覧

指定した事業者の全路線と駅を表示します。

get_operator_routes(operator_name: "yurikamome")

10. list_ferry_ports — フェリー/水上バス港一覧

東海汽船（伊豆諸島航路）と東京クルーズ（水上バス）の全港を表示します。

list_ferry_ports(language: "ja")

11. search_ferry — フェリー/水上バス航路検索

港間の航路と時刻表を検索します。検索前に気象庁の津波警報・注意報を確認し、出発・到着港の津波予報区に有効な警報がある場合は、航路・時刻表を返さず水路移動を中止する安全案内へ切り替えます。

通常時のレスポンスには maritime_safety_status を含め、気象庁の津波情報を確認した時刻・公式情報リンクを返します。

search_ferry(from_port: "東京", to_port: "大島")
search_ferry(from_port: "浅草", to_port: "浜離宮")

12. list_community_buses — 東京都コミュニティバス一覧

東京バス協会「東京バス案内WEB」掲載の41自治体のコミュニティバスを自治体別に一覧表示します（ちぃばす・ハチ公バス・ムーバス・すぎ丸・はなバス 等）。各バスの公式サイトURL付きで、時刻表・路線の詳細はリンク先で確認できます。日本語・英語・中国語の3言語対応です。

list_community_buses(language: "ja")   # ja / en / zh

🚨 障害シミュレーション（-testモード）

開発時や動作検証時に実際の悪天候や交通障害を想定したテストが行えるよう、擬似的な障害を発生させるテストモードを用意しています。search_route に -test フラグを付けると実際の外部APIを呼ばずにシミュレーションできます。日本語・英語・中国語のキーワード入力に対応しています。

例:

浅草から渋谷までの経路を調べて -test 地震
Check route from Asakusa to Shibuya -test typhoon
查询从浅草到涩谷的路线 -test 台风

🛡 エラーハンドリング

ネットワーク障害や外部APIのタイムアウトが発生した場合でも、LLMが迅速・適切にフォールバック処理や理由説明を行えるよう、全エラーは構造化された統一JSON形式で出力されます。

{
  "status": "ERROR",
  "error_type": "NETWORK_ERROR",
  "error_code": 502,
  "retryable": false,
  "suggestions": ["Yahoo!路線情報の直接検索をご利用ください。"],
  "fallback_url": "https://transit.yahoo.co.jp/..."
}

🔄 システム構成

MCPクライアントからのコンテキストリクエストを受け取り、各種オープンデータ・API（ODPT/気象庁/GBFS/GTFS）へ安全かつ高速にアクセスするアーキテクチャの概要です。

┌─────────────────────────────────────────┐
│           MCP Client                    │
│  (Claude Desktop / Hermes / etc.)      │
└──────────────────┬──────────────────────┘
                   │ stdio
┌──────────────────▼──────────────────────┐
│       Tokyo Transit MCP Server         │
│────────────────────────────────────────┤
│  search_route   get_weather            │
│  search_fare    get_timetable          │
│  search_bus     search_flight          │
│  get_station_info  get_operator_routes │
│  list_transit_operators  list_ferry_ports │
│  search_ferry   list_community_buses   │
│────────────────────────────────────────┤
│  🛡 Circuit Breaker  📦 Cache Layer   │
│  🌐 Multilingual       🚲 GBFS Client │
└───┬────────┬────────┬────────┬─────────┘
    │        │        │        │
    ▼        ▼        ▼        ▼
 ODPT      JMA     GBFS     GTFS
  API      API     API     (Ferry)

📊 キャッシュ戦略

外部APIへの不要なリクエストを削減し、応答速度の向上とアクセス制限の回避を実現するため、データ特性に応じた適切なTTL（有効期限）を設定しています。

🔐 必要な環境変数

主要機能であるODPT（公共交通オープンデータセンター）連携には、以下の環境変数の設定が必要です。

🏗 プロジェクト構成

本プロジェクトのディレクトリ構造と主要ファイルの構成です。

tokyo-transit-mcp/
├── src/
│   ├── index.mjs            # サーバー起動・ツール登録・エクスポート再公開（v2.39.0 で155行にスリム化）
│   ├── config.mjs           # 共有状態（envConfig / cache / CircuitBreaker / API定数）
│   ├── data/                # 路線・駅・バス・フェリー・ランドマーク・多言語辞書データ
│   │   ├── station-names.mjs
│   │   ├── railway-lines.mjs
│   │   ├── landmarks.mjs
│   │   ├── ferry-ports.mjs
│   │   ├── bus-routes.mjs
│   │   └── misc.mjs
│   ├── lib/                 # 純関数ユーティリティ（lang / csv / geo / time / common）
│   ├── advice/              # AIアドバイス・天気・地震安全（transit-advice / weather / earthquake）
│   └── handlers/            # 各ツール実装（search-route / bus / ferry / fare / timetable / flight / station-info）
├── scripts/            # 回帰検証プローブ（多言語・バス乗り継ぎ・言語検出）
│   ├── probe-all-lang.mjs
│   ├── probe-bus-transfer-lang.mjs
│   └── probe-language-detection.mjs
├── package.json
├── package-lock.json
├── README.md
├── SKILL.md             # プロジェクトスキル定義
├── mcp.json             # MCPクライアント設定例
├── .env.example         # 環境変数サンプル
└── .env                 # APIキー（gitignore推奨）

依存方向は handlers → advice/data/lib → config の一方通行（v2.39.0 モノリス分割・イシュー#75）。

⚠️ ライセンス

MIT License

🙏 謝辞

• 公共交通オープンデータセンター（ODPT）

• 気象庁 API

• ドコモ・バイクシェア GBFS

🚃 Tokyo Transit MCP Server

Integrated Tokyo Metropolitan Area Public Transit Information MCP Server powered by ODPT API + Japan Meteorological Agency API

Search across every mode of transport in the Tokyo area — trains, monorails, AGT, trams, water buses, ferries, buses, and bike-sharing — through a single MCP server. AI Intelligent Advice based on weather and operational status is generated automatically in Japanese, English, and Chinese.

✨ Features

Beyond simple route search, this server integrates weather data and public transit open data (ODPT / GBFS / GTFS) to deliver real-time transit advice. Key features:

🚉 Integrated Transit Agencies

Covers 124 lines / 1,430 stations (route search runs on the built-in graph without an API key):

🛤️ Latest Updates

• Fixed transit API failure handling, ambiguous bus-stop search, and cache behavior found in the code audit (v2.42.1)

  • Fixed timetable API failure classification: failures while loading ODPT railway data are no longer reported as NO_DATA; they notify the circuit breaker and remain API errors

  • Paused ambiguous bus-stop searches: matches spanning multiple operators or areas now return AMBIGUOUS_BUS_STOP with candidates instead of silently selecting the first result

  • Made the cache a true LRU: accessed entries are marked as recently used, reducing unnecessary refetches when the cache reaches its limit

  • Improved API error classification: authentication failures (401/403), server failures (5xx), timeouts, and internal errors are distinguished in structured responses

  • Verification — node --check for all changed modules, regression tests, live route/bus-stop/timetable smoke tests, and git diff --check PASS

🤖 AI Intelligent Advice

Generates concrete, useful advice for your trip based on weather and operational status.

• ☀ Sunny — supports comfortable travel

• ☔ Rainy — warns about slippery station floors and stairs, recommends bus alternatives

• 🌡 High Temperature — heatstroke alert and hydration reminder

• ❄ Snow — warns of icy surfaces, delays, and possible suspensions; recommends allowing extra time

• 🚨 Emergency — automatically shows shelter/evacuation links during service suspensions or disasters

🛡 Safety & Fault Tolerance

• Circuit Breaker — 3 consecutive failures → 60s cooldown (gradually extended)

• Unified Cache Management — reduces API load by up to 80% (up to 24h caching)

• Degraded Mode — keeps partial operation during API disruptions

• Severe Weather Logic — automatically hides bike guidance during typhoons or flooding

• LLM-Friendly JSON — errors are emitted as structured data so AI can interpret context, retryability, and next options

💬 Easy Search in Natural Language

Station, bus stop, and port names are automatically resolved by partial match, notation variance, and legacy names, so exact input is not required. Simply pass natural expressions in Japanese, English, or Chinese — e.g. "route from Skytree to Telecom Center", "Odaiba to Toyosu", or "bus to Tokyo Big Sight".

Search examples:

route from Skytree to Telecom Center
Shibuya to Odaiba route
查询从浅草到台场的路线
bus stop near Tokyo Big Sight
ferry to Oshima from Tokyo

⚠️ Note: This server displays responses through an LLM model on the MCP client (Claude Desktop / Hermes, etc.). Depending on the model, minor display variance (differences in wording, whether advice is omitted, etc.) may occur for the AI Intelligent Advice and search results. The search engine's own JSON output is model-independent and consistent, but the final phrasing depends on the model in use.

🌐 Multi-Language Support

The full response — AI advice, station and line names, weather text, and errors — is localized in Japanese, English, or Chinese to match the user's question.

The language is normally inferred from the question. When Japanese station names are used in an English or Chinese request, pass language: "en" or language: "zh" to ensure the intended response language.

🔧 Test Mode (-test)

Adding -test <disruption_type> to search_route simulates 20+ types of transport disruptions. See the "Disruption Simulation" section for details.

📦 Setup

Clone the repository, install dependencies, then add the configuration to your MCP client (Claude Desktop / Hermes, etc.).

# Clone the repository
git clone https://github.com/loosephoto/tokyo-transit-mcp.git
cd tokyo-transit-mcp

# Install dependencies
npm install

# Set your ODPT API key (Get one from https://developer.odpt.org/)
echo 'ODPT_API_KEY=your_api_key_here' > .env
# Only if using flight times: set AviationStack API key (optional: https://aviationstack.com/)
echo 'FLIGHT_API_KEY=your_flight_api_key_here' >> .env

MCP Client Configuration Example (Claude Desktop / Hermes, etc.)

Keep API keys only in the repository-root .env; do not put them in the MCP client's configuration file. The server resolves .env relative to src/config.mjs, so it does not depend on the MCP client's working directory.

{
  "mcpServers": {
    "tokyo-transit": {
      "command": "node",
      "args": ["/path/to/tokyo-transit-mcp/src/index.mjs"]
    }
  }
}

Set the keys in /path/to/tokyo-transit-mcp/.env:

ODPT_API_KEY=your_api_key_here
FLIGHT_API_KEY=your_flight_api_key_here

Do not share or commit .env; it contains secrets.

🛠 Available Tools

This MCP server provides 12 tools. See the quick-reference table for an overview and the sections below for details.

1. search_route — Route Search (Main Feature)

Function: Searches a route from departure to arrival station, automatically fetches weather and transit status, and adds AI advice. The entire response (station/line names, weather, errors) is auto-localized to the input language (ja/en/zh).

search_route(from: "Shibuya", to: "Shinjuku")

Parameters:

• from (string) — Departure station name

• to (string) — Arrival station name

• language (string, optional) — Force response language ja / en / zh. When omitted, the language is auto-detected from the station names; pass the user's query language to guarantee the response language (e.g. pass language: "en" when the user asked in English even if the station names are Japanese)

• user_location (object, optional) — User's current location { lat: number, lon: number }. When provided, bike-share guidance during service suspensions is based on the current location (otherwise on the departure station)

Examples:

search_route(from: "Tokyo", to: "Sanrio Puroland", language: "en")
search_route(from: "Tokyo", to: "Mori Art Museum", language: "en")
search_route(from: "东京", to: "三丽鸥彩虹乐园", language: "zh")
search_route(from: "Shibuya", to: "Yoyogi Park", language: "en")
search_route(from: "涩谷", to: "代代木公园", language: "zh")

Response Example:

{
  "status": "SUCCESS",
  "from": "Shibuya",
  "to": "Shinjuku",
  "weather_text": "Tokyo Area: Sunny",
  "direct_search_url": "https://transit.yahoo.co.jp/...",
  "ai_transit_advice": "🤖 【AI Intelligent Advice】\nIt's nice and sunny!...",
  "community_bus_access": [{ "station": "Shibuya", "buses": [{ "bus": "Hachiko Bus", "stop": "Shibuya Stn East Exit" }] }],
  "gov_facility_search_support": { "...": "..." },
  "station_bus_stops": { "...": "..." },
  "fare_available": true
}

Test Mode (see the Disruption Simulation section below for details):

search_route(from: "Tokyo -test typhoon", to: "Shinjuku")
search_route(from: "Shinjuku -test earthquake", to: "Shibuya")
search_route(from: "东京 -test 台风", to: "新宿")

2. get_station_info — Station Info

Gets basic station information (serving lines, operators, etc.).

get_station_info(station_name: "Shibuya", operator: "tokyometro")

3. get_weather — Weather Info

Fetches weather and temperature from the JMA API. Displays a heatstroke caution when hot.

get_weather(area_name: "Tokyo")

4. search_fare — Fare Search

Searches fares between two stations from ODPT data (Tokyo Metro, Toei, Yokohama Municipal Subway, Tsukuba Express, Rinkai Line, Yurikamome, Tama Monorail).

search_fare(from: "Shibuya", to: "Shinjuku")

{
  "fares": [{ "operator": "TokyoMetro", "ticket": 200, "ic": 198 }]
}

5. get_timetable — Timetable Search

Searches the timetable of a station from ODPT data.

get_timetable(station_name: "Shibuya", railway: "Yamanote Line")

6. search_bus — Bus Route & Transfer Search

search_bus(busstop_name: "Shibuya Station")
search_bus(from: "Shibuya Station", to: "Shimbashi Station")
search_bus(from: "Asakusa", to: "Ueno", vehicle: "bus")

Development & regression checks

After code changes, run the syntax check and multilingual regression probes. npm test checks not only the main results but also auxiliary fields such as weather_text, nearby_suggestions, station names, and line names.

npm run build        # node --check src/index.mjs
npm test             # 26 Japanese / English / Chinese regression cases
npm run test:bus     # live bus-transfer probe; may take a long time depending on the API
npm run test:vehicle # deterministic vehicle-preference mock regression

Use the exit code of npm test as the CI quality gate. A timeout in the live bus-transfer probe should be evaluated separately from the deterministic mock regressions.

7. search_flight — Airport Flight Times & Arrival Display

search_flight(airport: "Haneda Airport", direction: "arrival")
search_flight(airport: "Narita Airport", direction: "arrival", destination: "Tokyo Station")
search_flight(flight_number: "NH001", direction: "arrival")

8. list_transit_operators — Transit Operators List

Lists all operators (rail, AGT, monorail, tram, ferry) with a type filter.

list_transit_operators(language: "en", type_filter: "all")

9. get_operator_routes — Routes by Operator

Lists all routes and stations of a given operator.

get_operator_routes(operator_name: "yurikamome")

10. list_ferry_ports — Ferry / Water Bus Ports List

Lists all ports of Tokai Kisen (Izu Islands routes) and Tokyo Cruise (water buses).

list_ferry_ports(language: "en")

11. search_ferry — Ferry / Water Bus Route Search

Searches routes and timetables between ports. Before returning them, it checks JMA tsunami warnings/advisories. When an active warning applies to the tsunami forecast area of either port, it stops route/timetable guidance and switches to water-travel safety guidance.

During normal conditions, the response includes maritime_safety_status with the JMA tsunami-information check time and official source link.

search_ferry(from_port: "Tokyo", to_port: "Oshima")
search_ferry(from_port: "Asakusa", to_port: "Hama-rikyu")

12. list_community_buses — Tokyo Community Buses

Lists 41 community buses across Tokyo wards/cities published by the Tokyo Bus Association, including Chii-bus, Hachiko Bus, Mu-Bus, Sugimaru, and Hanabus. Each entry comes with the official municipal website URL for timetables and routes. Available in Japanese, English, and Chinese.

list_community_buses(language: "ja")   # ja / en / zh

🚨 Disruption Simulation (-test mode)

To test system behavior under severe weather or transit disruptions during development, a test mode is provided. Appending -test <disruption_type> to search_route triggers simulated responses without calling real APIs. Supports multilingual keywords (English, Japanese, Chinese).

Example:

Check route from Asakusa to Shibuya -test typhoon
Check route from Asakusa to Shibuya -test earthquake
查询从浅草到涩谷的路线 -test 台风

🛡 Error Handling

All errors are returned in a unified JSON format so that LLMs can quickly and appropriately fall back or explain the reason.

{
  "status": "ERROR",
  "error_type": "NETWORK_ERROR",
  "error_code": 502,
  "retryable": false,
  "suggestions": ["Please search directly on Yahoo! Transit."],
  "fallback_url": "https://transit.yahoo.co.jp/..."
}

🔄 System Architecture

Architecture overview showing context requests from MCP clients routed to open APIs (ODPT/JMA/GBFS/GTFS) safely and efficiently.

┌─────────────────────────────────────────┐
│           MCP Client                    │
│  (Claude Desktop / Hermes / etc.)      │
└──────────────────┬──────────────────────┘
                   │ stdio
┌──────────────────▼──────────────────────┐
│       Tokyo Transit MCP Server         │
│────────────────────────────────────────┤
│  search_route   get_weather            │
│  search_fare    get_timetable          │
│  search_bus     search_flight          │
│  get_station_info  get_operator_routes │
│  list_transit_operators  list_ferry_ports │
│  search_ferry   list_community_buses   │
│────────────────────────────────────────┤
│  🛡 Circuit Breaker  📦 Cache Layer   │
│  🌐 Multilingual       🚲 GBFS Client │
└───┬────────┬────────┬────────┬─────────┘
    │        │        │        │
    ▼        ▼        ▼        ▼
 ODPT      JMA     GBFS     GTFS
  API      API     API     (Ferry)

📊 Caching Strategy

Appropriate TTLs (Time To Live) are configured according to data update frequencies to reduce unnecessary API calls and ensure high performance.

🔐 Required Environment Variables

Integrating with ODPT (Open Data Center for Public Transportation) requires the following environment variables.

🏗 Project Structure

Directory layout and key files of this project.

tokyo-transit-mcp/
├── src/
│   ├── index.mjs            # Server bootstrap, tool registration, re-exports (slimmed to 155 lines in v2.39.0)
│   ├── config.mjs           # Shared state (envConfig / cache / CircuitBreaker / API constants)
│   ├── data/                # Lines/stations/buses/ferries/landmarks/multilingual dictionaries
│   │   ├── station-names.mjs
│   │   ├── railway-lines.mjs
│   │   ├── landmarks.mjs
│   │   ├── ferry-ports.mjs
│   │   ├── bus-routes.mjs
│   │   └── misc.mjs
│   ├── lib/                 # Pure-function utilities (lang / csv / geo / time / common)
│   ├── advice/              # AI advice / weather / earthquake safety (transit-advice / weather / earthquake)
│   └── handlers/            # Tool implementations (search-route / bus / ferry / fare / timetable / flight / station-info)
├── scripts/            # Regression probes (multilingual / bus transfer / language detection)
│   ├── probe-all-lang.mjs
│   ├── probe-bus-transfer-lang.mjs
│   └── probe-language-detection.mjs
├── package.json
├── package-lock.json
├── README.md
├── SKILL.md             # Project skill definition (v2.25.4)
├── mcp.json             # MCP client configuration example
├── .env.example         # Environment variables sample
└── .env                 # API Keys

Dependency direction is one-way: handlers → advice/data/lib → config (v2.39.0 monolith split, issue #75).

⚠️ License

MIT License

🙏 Acknowledgments

• Open Data Center for Public Transportation (ODPT)

• Japan Meteorological Agency (JMA) API

• Docomo Bike Share GBFS

🚃 Tokyo Transit MCP Server

整合 ODPT API + 日本气象厅 API 的东京圈综合交通信息 MCP 服务器

铁路、单轨铁路、AGT、有轨电车、水上巴士、轮渡、公交与共享单车——东京圈的全部出行方式可通过一个 MCP 服务器跨方式查询。结合天气与运行状况，自动生成日语、英语、中文的 AI 智能出行建议。

✨ 特性

本服务器不仅提供简单的路线搜索，更整合了气象数据与各类公共交通开放数据（ODPT / GBFS / GTFS），提供实时的出行建议。主要特性如下：

🚉 整合所有公共交通工具

共覆盖124条线路/1,430站（路线搜索由无需 API 密钥的内置图执行）：

🛤️ 最近更新

• 改善代码审计议题#93中的潜在缺陷、稳健性与性能（v2.41.0）

  • 修正断路器分级冷却（#93）: 原先按失败次数计算，threshold>1 时 60/120 秒会在开启前被覆盖、从未生效。现按开启（trip）次数单调延长 60秒→120秒→180秒

  • 天气获取失败时通知 jmaBreaker.onFailure（#93）: JMA API 错误不会增加失败计数，导致 jmaBreaker 一直不生效。现 getWeatherAdvice 获取失败必通知

  • 实现 search_route 的优雅降级（#93）: 外部API（气象厅/ODPT运行信息）被切断时，仍由内置路线引擎计算路线并以 degraded_mode: true 返回（原先直接报错中断）

  • 将迪杰斯特拉的优先队列改为最小堆（#93）: 将每次循环的数组排序（O(N log N)）改为二叉堆（O(log N)），并以插入顺序的 FIFO 打破平局，保持原有路线选择一致

  • 缓存上限逐出改为 O(1)（#93）: 将 Object.entries 的 O(N) 全遍历改为按 Map 插入顺序 O(1) 逐出最旧条目（近似LRU）

  • 将 GTFS ZIP/CSV 解析移至工作线程（#93）: 高达95万行的 stop_times.txt 在专用线程处理，避免阻塞事件循环

  • 强化强风与特别警报检测（#93）: 增加强风表述（「风が强く」「強い风」等），特别警报与警报・注意报概況文交叉核对。gtfs.mjs 的 src.date() 增加函数检查

  • 验证 — build 通过・probe-all-lang 26/26・test:walk ALL PASS・test:bus ALL PASS・test:issue（84/80/82-83/88-89-90/91-92）全PASS・新逻辑单测 23项 ALL PASS

🤖 AI 智能建议

根据天气与运行状况，自动生成具体实用的出行建议。

• ☀ 晴天 — 提供舒适的出行建议

• ☔ 雨天 — 提醒站内及楼梯湿滑，推荐公交替代出行

• 🌡 高温 — 提供中暑警报和补水提醒

• ❄ 降雪 — 提醒路面结冰、延误和可能停运，并建议预留充足时间

• 🚨 紧急情况 — 线路停运或检测到灾害时自动显示避难所/疏散链接

🛡 安全性与容错

• 断路器 — 连续 3 次失败后冷却 60 秒（逐步延长）

• 统一缓存管理 — 最多降低 80% API 负载（最长缓存 24 小时）

• 降级模式 — API 故障时保持部分功能运行

• 恶劣天气安全逻辑 — 台风或洪水时自动隐藏自行车指引

• LLM 友好 JSON — 以便 AI 理解当前状况、是否可重试和下一步选择的结构化数据输出所有错误

💬 自然语言轻松搜索

车站名、公交站名、港口名均支持部分匹配、表记差异及旧名自动解析，无需精确输入即可直观搜索。只需直接传入日语、英语或中文的自然表达，例如「从晴空塔到电信中心」「Odaiba 到 Toyosu」「到东京国际展览中心的巴士」即可。

搜索示例:

从晴空塔到电信中心的路线
Shibuya to Odaiba route
查询从浅草到台场的路线
东京国际展览中心附近的巴士站
从东京前往大岛的渡轮

⚠️ 注意: 本服务器通过 MCP 客户端（Claude Desktop / Hermes 等）上的 LLM 模型显示回答。因模型不同，AI 智能建议与搜索结果的显示可能存在细微差异（措辞不同、是否省略建议等）。搜索引擎自身的 JSON 输出与模型无关且保持一致，但最终表述取决于所使用的模型。

🌐 多语言支持

自动识别输入语言，并将整个响应本地化为该语言——不仅是 AI 建议，路线中的站名、线路名、天气文本和错误消息也会以用户的语言返回。

包含符号（箭头、斜杠、括号）的英语输入，以及包含简体字或中文功能词（到・从・前往・出发 等）的输入均可准确识别。

🔧 测试模式 (-test)

在 search_route 中加入 -test <故障类型> 即可模拟 20 多种交通中断或灾害场景。详见「故障模拟」一节。

📦 安装与设置

请依次完成克隆代码库、安装依赖项，并将配置添加到您的 MCP 客户端（如 Claude Desktop 或 Hermes）。

# 克隆代码库
git clone https://github.com/loosephoto/tokyo-transit-mcp.git
cd tokyo-transit-mcp

# 安装依赖
npm install

# 设置 ODPT API 密钥（可从 https://developer.odpt.org/ 获取）
echo 'ODPT_API_KEY=your_api_key_here' > .env
# 仅在需要航班时刻时设置（AviationStack API 密钥・可选: https://aviationstack.com/）
echo 'FLIGHT_API_KEY=your_flight_api_key_here' >> .env

MCP 客户端配置示例（Claude Desktop / Hermes 等）

API 密钥仅保存于仓库根目录的 .env 中，不要写入 MCP 客户端配置文件。服务器会以 src/config.mjs 的位置为基准读取 .env，不依赖 MCP 客户端的工作目录。

{
  "mcpServers": {
    "tokyo-transit": {
      "command": "node",
      "args": ["/path/to/tokyo-transit-mcp/src/index.mjs"]
    }
  }
}

请在 /path/to/tokyo-transit-mcp/.env 中设置：

ODPT_API_KEY=your_api_key_here
FLIGHT_API_KEY=your_flight_api_key_here

.env 包含密钥，请勿分享或提交到版本库。

🛠 可用工具

本 MCP 服务器共提供 12 个工具。概览请参考速查表，详细说明请参考各小节。

1. search_route — 换乘路线搜索（核心功能）

功能: 查询出发站至到达站的路线，自动获取天气与运行状态并附带 AI 出行建议。整个响应（站名、线路名、天气、错误消息）将按输入语言（日/英/中）自动本地化。

search_route(from: "渋谷", to: "新宿")

参数:

• from (string) — 出发车站名称

• to (string) — 到达车站名称

• language (string, 可选) — 强制指定响应语言 ja / en / zh。省略时根据站名自动判定；若按用户的查询语言指定，可确保以该语言响应（例：用户用英语提问但站名为日语时，传入 language: "en" 即可获得英语回复）

• user_location (object, 可选) — 用户当前位置 { lat: number, lon: number }。指定时，运行中断期间的共享自行车指引以当前位置为基准（未指定时以出发站为基准）

输入示例:

search_route(from: "东京", to: "三丽鸥彩虹乐园", language: "zh")
search_route(from: "Tokyo", to: "Mori Art Museum", language: "en")
search_route(from: "涩谷", to: "代代木公园", language: "zh")
search_route(from: "Shibuya", to: "Yoyogi Park", language: "en")

响应示例:

{
  "status": "SUCCESS",
  "from": "渋谷",
  "to": "新宿",
  "weather_text": "东京地区: 晴",
  "direct_search_url": "https://transit.yahoo.co.jp/...",
  "ai_transit_advice": "🤖 【AI智能出行建议】\n天气晴朗！...",
  "community_bus_access": [{ "station": "涩谷", "buses": [{ "bus": "哈奇公巴士", "stop": "涩谷站东口" }] }],
  "gov_facility_search_support": { "...": "..." },
  "station_bus_stops": { "...": "..." },
  "fare_available": true
}

测试模式（故障模拟详见下文）:

search_route(from: "东京 -test 人身事故", to: "新宿")
search_route(from: "新宿 -test 台风", to: "涩谷")
search_route(from: "Tokyo -test typhoon", to: "Shinjuku")

2. get_station_info — 获取车站信息

获取指定车站的基本信息（途经线路、运营商等）。

get_station_info(station_name: "渋谷", operator: "tokyometro")

3. get_weather — 获取天气信息

从气象厅 API 获取天气与气温。高温时显示中暑注意。

get_weather(area_name: "東京")

4. search_fare — 票价查询

从 ODPT 数据查询两站之间的票价（东京地下铁、都营、横滨市营地铁、筑波快线、临海线、百合海鸥号、多摩单轨电车）。

search_fare(from: "渋谷", to: "新宿")

{
  "fares": [{ "operator": "TokyoMetro", "ticket": 200, "ic": 198 }]
}

5. get_timetable — 时刻表查询

从 ODPT 数据查询指定车站的时刻表。

get_timetable(station_name: "渋谷", railway: "山手線")

6. search_bus — 公交路线与换乘查询

search_bus(busstop_name: "涩谷站前")
search_bus(from: "涩谷站前", to: "新桥站前")
search_bus(from: "浅草", to: "上野", vehicle: "bus")

开发与回归验证

代码变更后，请运行语法检查和多语言回归探针。npm test 不仅检查主要结果，也会检查 weather_text、nearby_suggestions、车站名和线路名等辅助显示字段。

npm run build        # node --check src/index.mjs
npm test             # 26 个日文/英文/中文回归用例
npm run test:bus     # 公交换乘实时 API 探针，可能因 API 状况耗时较长
npm run test:vehicle # 乘车工具优先的确定性 mock 回归

可以使用 npm test 的退出码作为 CI 质量门槛。实时公交换乘探针超时，应与确定性 mock 回归分开判断。

7. search_flight — 机场航班时刻与到达信息

search_flight(airport: "羽田机场", direction: "arrival")
search_flight(airport: "成田机场", direction: "arrival", destination: "东京站")
search_flight(flight_number: "NH001", direction: "arrival")

8. list_transit_operators — 交通运营商列表

列出全部运营商（铁路、AGT、单轨、有轨电车、轮渡），支持类型筛选。

list_transit_operators(language: "zh", type_filter: "all")

9. get_operator_routes — 按运营商列出路线

列出指定运营商的全线路与车站。

get_operator_routes(operator_name: "yurikamome")

10. list_ferry_ports — 轮渡/水上巴士港口列表

列出东海汽船（伊豆群岛航线）与东京观光汽船（水上巴士）的全部港口。

list_ferry_ports(language: "zh")

11. search_ferry — 轮渡/水上巴士航线搜索

查询港口之间的航线与时刻表。返回结果前会检查气象厅的海啸警报/注意报；当出发港或到达港所属的海啸预报区有有效警报时，系统不返回航线或时刻表，而切换为水路安全指引。

正常情况下，响应会包含 maritime_safety_status，其中提供气象厅海啸信息的检查时间和官方来源链接。

search_ferry(from_port: "东京", to_port: "大岛")
search_ferry(from_port: "浅草", to_port: "滨离宫")

12. list_community_buses — 东京都社区公交一览

按自治体列出东京巴士协会「东京巴士指南WEB」收录的 41 条社区公交（ちぃばす、哈奇公巴士、ムーバ斯、すぎ丸、はな巴士 等）。每条均附带官方网址，时刻表与路线详情请在链接中确认。支持日语、英语、中文。

list_community_buses(language: "ja")   # ja / en / zh

🚨 故障模拟（-test 模式）

为了在开发和验证过程中模拟恶劣天气或交通中断，可使用测试模式。在 search_route 中指定 -test <故障类型> 即可触发模拟响应，无需调用实际 API。支持中文、英文、日文多语言关键字。

示例:

查询从浅草到涩谷的路线 -test 台风
查询从浅草到涩谷的路线 -test 地震
Check route from Asakusa to Shibuya -test typhoon

🛡 错误处理

网络故障或外部 API 超时时，所有错误均统一输出为结构化 JSON 格式，方便 LLM 快速进行降级处理或说明原因。

{
  "status": "ERROR",
  "error_type": "NETWORK_ERROR",
  "error_code": 502,
  "retryable": false,
  "suggestions": ["请直接访问 Yahoo! 路线情报进行搜索。"],
  "fallback_url": "https://transit.yahoo.co.jp/..."
}

🔄 系统架构

MCP 客户端的请求通过 stdio 传递给服务器，服务器安全高效地整合 ODPT、气象厅、GBFS 及 GTFS 等接口。

┌─────────────────────────────────────────┐
│           MCP Client                    │
│  (Claude Desktop / Hermes / etc.)      │
└──────────────────┬──────────────────────┘
                   │ stdio
┌──────────────────▼──────────────────────┐
│       Tokyo Transit MCP Server         │
│────────────────────────────────────────┤
│  search_route   get_weather            │
│  search_fare    get_timetable          │
│  search_bus     search_flight          │
│  get_station_info  get_operator_routes │
│  list_transit_operators  list_ferry_ports │
│  search_ferry   list_community_buses   │
│────────────────────────────────────────┤
│  🛡 Circuit Breaker  📦 Cache Layer   │
│  🌐 Multilingual       🚲 GBFS Client │
└───┬────────┬────────┬────────┬─────────┘
    │        │        │        │
    ▼        ▼        ▼        ▼
 ODPT      JMA     GBFS     GTFS
  API      API     API     (Ferry)

📊 缓存策略

根据数据更新频率设置合理的 TTL（生存时间），以减少不必要的 API 请求，提高响应速度。

🔐 必需的环境变量

与 ODPT（公共交通开放数据中心）集成需要设置以下环境变量。

🏗 项目结构

本项目的目录结构及主要文件：

tokyo-transit-mcp/
├── src/
│   ├── index.mjs            # 服务器启动・工具注册・导出名重新导出（v2.39.0 精简至155行）
│   ├── config.mjs           # 共享状态（envConfig / cache / CircuitBreaker / API常量）
│   ├── data/                # 线路・车站・巴士・轮渡・地标・多语言词典数据
│   │   ├── station-names.mjs
│   │   ├── railway-lines.mjs
│   │   ├── landmarks.mjs
│   │   ├── ferry-ports.mjs
│   │   ├── bus-routes.mjs
│   │   └── misc.mjs
│   ├── lib/                 # 纯函数工具（lang / csv / geo / time / common）
│   ├── advice/              # AI建议・天气・地震安全（transit-advice / weather / earthquake）
│   └── handlers/            # 各工具实现（search-route / bus / ferry / fare / timetable / flight / station-info）
├── scripts/            # 回归验证探针（多语言 / 公交换乘 / 语言检测）
│   ├── probe-all-lang.mjs
│   ├── probe-bus-transfer-lang.mjs
│   └── probe-language-detection.mjs
├── package.json
├── package-lock.json
├── README.md
├── SKILL.md             # 项目技能定义
├── mcp.json             # MCP 客户端配置示例
├── .env.example         # 环境变量示例
└── .env                 # API 密钥

依赖方向为 handlers → advice/data/lib → config 单向（v2.39.0 单体拆分・议题#75）。

⚠️ 许可证

MIT License

🙏 致谢

• 公共交通开放数据中心 (ODPT)

• 日本气象厅 API

• Docomo Bike Share GBFS