transitland-mcp-server

---

概要

GTFS、GTFS-Realtime、GBFS フィードのオープンなアグリゲーターである Transitland の、世界中の数千の運行事業者の交通データを提供します。運行事業者とそのフィードを検索し、路線、停留所、リアルタイムの出発情報を調べられます。

ツール

ツール	説明
transitland_find_operators	名前、地点／半径、境界ボックス、国／地域、または Onestop ID で交通事業者／機関を検索します
transitland_get_operator	Onestop ID で運行事業者の完全なレコード（機関、フィード、ソースタグ）を取得します
transitland_find_feeds	GTFS、GTFS-Realtime、GBFS フィードを検索し、取得 URL、ライセンス条件、更新状況を確認します
transitland_find_routes	地点／半径、境界ボックス、運行事業者、Onestop ID、または GTFS モードで路線を検索します
transitland_find_stops	名前、地点／半径、境界ボックス、Onestop ID、または運行事業者のネットワークで停留所／駅を検索します
transitland_get_departures	停留所からの出発情報を取得し、それぞれに realtime の true／false を付けます

Transitland は地名をジオコーディングしません。地理情報で絞り込むツールを呼び出す前に、ジオコーディング用 MCP サーバー（例：openstreetmap-mcp-server の openstreetmap_geocode）を使って、場所を座標に変換してください。

リソース

リソース	説明
transitland://operator/{onestop_id}	Onestop ID による事業者レコード — 事業者、サービス提供地域、公開フィード、ソースタグ
transitland://feed/{onestop_id}	Onestop ID によるフィードレコード — 仕様、取得 URL、ライセンス条項、鮮度

すべてのリソースデータには、ツール（transitland_get_operator、transitland_find_feeds）からもアクセスできます。

機能リファレンス

ページのデフォルト上限は 20、最大上限は 100 です。より大きな limit は通知とともに上限値に丸められ、ページが上限に達すると truncated、shown、cap が表示されます。続きの取得には、返された after カーソルを使用してください。

transitland_find_operators _ツール

• search（名称）、lat+lon+radius（最大 100,000m、デフォルト 1,000m）、bbox、onestop_id、または adm0_name／adm1_name（国／地域）で絞り込みます。少なくとも 1 つは必須です。指定しない場合、呼び出しは no_filter として失敗します。
• lat を指定する場合は lon も必要です（逆も同様）。指定しない場合、呼び出しは incomplete_point として失敗します。
• 各事業者の Onestop ID、名称、サービス提供地域、公開フィード（GTFS_RT の項目は、リアルタイムの出発情報が利用可能な場合があることを示します）、Wikidata QID を返します。

---

transitland_get_operator _ツール

• Onestop ID（例：o-9q9-bart）または内部整数 ID を受け付けます。
• 事業者（それぞれサービス提供地域を含む）、公開フィード、ソースタグ（Wikidata QID、米国 NTD ID、一般的な Twitter/X ハンドル）を返します。
• ID が解決できない場合は operator_not_found になります。

---

transitland_find_feeds _ツール

• operator_onestop_id（transitland_find_operators から取得）、spec（gtfs／gtfs-rt／gbfs／mds。大文字・小文字の違いや、GTFS_RT のようなアンダースコア／ハイフンの違いも受け付けます）、search、または fetch_error で絞り込みます。少なくとも 1 つは必須です。
• 各フィードについて、取得 URL、リアルタイムエンドポイント、鮮度（最終取得日時、コンテンツハッシュ、対象となるカレンダー期間）、ライセンス条項を返します。ライセンス条項には、再配布、商用利用、派生製品、帰属表示の可否が yes／no／unknown で示されます。空欄から推測されることはありません。判明している場合は、SPDX 識別子と帰属表示テキストも返します。
• authorizationRequired は、ダウンロードに別途キーまたは登録が必要なフィードを示します。

---

transitland_find_routes _ツール

• lat+lon+radius（最大 50,000m、デフォルト 1,000m）、bbox、operator_onestop_id、onestop_id、route_type（GTFS のモードを示す整数）、または search で絞り込みます。少なくとも 1 つは必須です。
• lat を指定する場合は lon も必要です（逆も同様）。指定しない場合、呼び出しは incomplete_point として失敗します。
• 短縮名／正式名、GTFS モード（バス、地下鉄、鉄道、フェリー、路面電車など）、ブランドカラー、運行事業者とソースフィードの Onestop ID を返します。路線種別がない場合は null、モードは unknown になります。
• 対象は時刻表に基づく（GTFS 静的）路線定義であり、リアルタイムの車両位置ではありません。

---

transitland_find_stops _ツール

• lat+lon+radius（最大 10,000m、デフォルト 500m）、bbox、onestop_id、served_by_onestop_ids（カンマ区切りの事業者／路線の Onestop ID）、または停留所名の search で絞り込みます。少なくとも 1 つは必須です。名称での検索にジオコーディングは不要です。
• 座標（上流データにない場合は null）、ラベル付きの location_type（停留所、駅、入口、ノード、乗降場所）、車椅子でのアクセス可否、タイムゾーン、子プラットフォームの場合は親駅の Onestop ID を返します。
• 出発情報はプラットフォームレベルの停留所（location_type 0）に紐付きます。駅には出発情報が返されない場合があるため、子プラットフォームを使用してください。

---

transitland_get_departures _tool

• まず transitland_find_stops で停留所を Onestop ID に解決してください。解決できない場合は stop_not_found になります。next_seconds は先読み時間を設定します。指定範囲は 60～86,400（デフォルトは 3,600）です。停留所から結果が返されない場合は、範囲を広げるか use_service_window: true を設定してください
• すべての出発情報には realtime フラグ（ライブの GTFS-Realtime 予測の場合は true、予定時刻の場合は false）と scheduleRelationship（STATIC、SCHEDULED、ADDED、CANCELED、UNSCHEDULED、DUPLICATED）が含まれます
• 遅延秒数を含む予定時刻と推定時刻、路線、行き先表示、交通機関の種別、便、方向、アクセシビリティ情報も返されます。トップレベルの realtimeAvailable は、停留所のフィードが GTFS-RT を配信しているかどうかを示します

---

transitland://operator/{onestop_id} _resource

• transitland_get_operator と同様に、事業者、サービス提供地域、公開フィード、ソースタグを返します
• onestop_id には Onestop ID（例：o-9q9-bart）または内部整数 ID を指定できます。解決できない場合は operator_not_found になります

---

transitland://feed/{onestop_id} _resource

• transitland_find_feeds の単一フィードの結果と同様に、仕様、取得 URL、リアルタイムエンドポイント、ライセンス条項、鮮度を返します
• onestop_id にはフィードの Onestop ID（例：f-9q9-bart）または内部整数 ID を指定できます。解決できない場合は feed_not_found になります
• 空欄のライセンスフィールドは unknown／null として返され、許容的なライセンスだと推測されることはありません

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログを提供します。

Transitland 固有の機能：

• Transitland v2 REST API 向けの直接 HTTP クライアントです。SDK への依存はなく、少数の GET エンドポイントを通じたシンプルなクエリパラメーター仕様です
• Onestop ID（o-／f-／r-／s-）を識別子の基軸としており、すべての結果に含まれ、入力時には内部整数 ID とともに使用できます
• フィード検索では最新のフィードバージョンの鮮度のみを返し、取得履歴全体は返しません
• 対象範囲のポリゴンと路線／停留所のジオメトリーは省略し、代わりに国／地域／市区町村の簡潔な地域概要を結果に含めます

エージェントに適した出力：

• リアルタイムの状態を明示します。各出発情報の realtime と scheduleRelationship に加え、トップレベルに realtimeAvailable を含めます
• 空欄のライセンスフィールドは unknown／null として返され、許容的なライセンスだと推測されることはありません。また、エージェントには再配布する前にライセンス URL で確認するよう案内します
• 上流のページネーション URL には API キーが含まれますが、公開されるのは不透明な after カーソルのみです。そのため、キーがツールの出力やログに含まれることはありません
• 結果が空の場合は、エラーではなく、次の操作に役立つ案内（まずジオコードする、検索範囲を広げる、子プラットフォームを試す）を返します

はじめに

以下を MCP クライアントの設定ファイルに追加してください。Transitland API キーが必要です。取得方法については前提条件をご覧ください。

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/transitland-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "TRANSITLAND_API_KEY": "your-api-key"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "transitland-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "TRANSITLAND_API_KEY=your-api-key",
        "ghcr.io/cyanheads/transitland-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 TRANSITLAND_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• Transitland v2 API キー。Transitland 開発者ポータルで登録してください。無料プランにはレート制限があり、Pro プランでは上限が引き上げられます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/transitland-mcp-server.git

2. ディレクトリに移動します：

cd transitland-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set TRANSITLAND_API_KEY

設定

すべての設定は、起動時に src/config/server-config.ts の Zod スキーマによって検証されます。TRANSITLAND_API_KEY が指定されていない場合、最初のツール呼び出し時ではなく、起動時に変数名を示すバナーが表示されて失敗します。

変数	説明	デフォルト
TRANSITLAND_API_KEY	必須。 Transitland v2 API キー。apikey クエリパラメーターとして送信されます。	—
TRANSITLAND_BASE_URL	Transitland REST API のベース URL。特定のデプロイ環境やセルフホストインスタンスに固定する場合に上書きします。	https://transit.land/api/v2/rest
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	MCP サーバーがマウントされる HTTP エンドポイントのパス。	/mcp
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）。	info
LOGS_DIR	ログファイル用のディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した呼び出しの引数と結果を、キー名に基づいて機密情報を伏せて記録します（自由形式の値に含まれるシークレットはそのまま残ります）。サイズは LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES で制限されます（デフォルトは 16384）。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry 計装（スパン、メトリクス、完了ログ）を有効にします。	false

オプションの上書き設定の全一覧は .env.example を参照してください。

HTTP セッションはデフォルトでステートレスです。上書きするには MCP_SESSION_MODE を設定してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t transitland-mcp-server .
docker run --rm -e TRANSITLAND_API_KEY=your-key -p 3010:3010 transitland-mcp-server

Dockerfile はデフォルトで HTTP トランスポートとステートレスセッションモードを使用し、ログを /var/log/transitland-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント。ツールとリソースを登録し、Transitland サービスを初期化します。
src/config	Zod を使用した、サーバー固有の環境変数の解析と検証。
src/mcp-server/tools	ツール定義（*.tool.ts）。運行事業者、フィード、路線、停留所、出発便に関する 6 つのツール。
src/mcp-server/resources	リソース定義（*.resource.ts）。運行事業者とフィードのレコード。
src/services/transitland	Transitland v2 REST クライアント。HTTP、apikey の挿入、カーソルの正規化、エラー分類、エンドポイントごとの型付きメソッドを担当します。
tests/	src/ に対応する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md / AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールロジック内で try/catch を使わないでください
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用してください
• src/mcp-server/*/definitions/index.ts のバレル経由で、新しいツールとリソースを登録してください
• Transitland API をラップする際は、未加工のデータを検証し、ドメイン型に正規化してから、出力スキーマを返してください。欠落しているフィールドを決して捏造しないでください（特にライセンス条項。空欄は「不明」を意味し、許可を意味するものではありません）

データとライセンス

交通データはTransitlandによって提供されています。Transitlandは、世界中の数千の事業者からGTFS、GTFS-Realtime、GBFSのフィードを集約するオープンなレジストリです。Transitlandのデータを基に構築した製品では、エンドユーザーからはっきり見える場所に、transit.land/termsへのリンクとともに「Transitland」という名称を表示する必要があります。

Transitlandは数千の事業者からフィードを集約しており、それぞれのフィードには独自のライセンスおよび帰属表示要件がある場合があります。このサーバーを通じて取得したデータを再配布または公開する前に、transit.land/termsでフィードごとのライセンス条項を確認し、各ソースフィードの要件を遵守してください。

貢献

Issueを歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEをご覧ください。