DB Timetable MCP Server

English | Deutsch

DB Timetable MCP サーバー

Deutsche Bahn の公式 Timetables API 用 Model Context Protocol サーバーです。コンパクトな DB XML をセマンティックな JSON に変換し、予定ダイヤとリアルタイムの変更を統合して、ひとつの駅の発着案内を作成します。

保証すること

• 正確なホームと時刻。 effective には表示する値が格納されます。planned と changed で変更内容を説明します。
• モデル向けの出力。 ツールは structuredContent、説明的な JSON スキーマ、および MCP リソースとして利用可能なデータモデルを返します。
• MCP への準拠。 公式 TypeScript SDK、ローカルクライアント向けの stdio、リモート運用向けのステートレスな Streamable HTTP を使用します。
• 安全なデフォルト設定。 stdout へのログ出力なし、変更しない限りループバックにバインド、ホスト許可リスト、タイムアウト、非 root コンテナ、再現可能なロックファイルを採用しています。
• 検証可能な動作。 単体テスト、コントラクトテスト、トランスポートテスト、カバレッジしきい値、CI、依存関係とシークレットのチェックを備えています。

クイックスタート

要件：Node.js 22 または 24 LTS、および DB API Marketplace で申し込んだ Timetables 製品。

git clone https://github.com/jorekai/db-timetable-mcp.git
cd db-timetable-mcp
npm ci
cp .env.example .env

.env に値を入力します。

DB_TIMETABLE_CLIENT_ID=deine-client-id
DB_TIMETABLE_CLIENT_SECRET=dein-api-key

次に、ビルドして起動します。

npm run build
npm start

stdio モードでは、プロセスは MCP クライアントからの接続を待ちます。ステータスメッセージは stderr のみに出力されます。stdout は JSON-RPC 専用です。

Claude Desktop

まず npm ci && npm run build を実行し、claude_desktop_config.json で絶対パスを指定します。

macOS/Linux：

{
  "mcpServers": {
    "db-timetable": {
      "command": "node",
      "args": ["/absolute/path/db-timetable-mcp/dist/index.js"]
    }
  }
}

Windows：

{
  "mcpServers": {
    "db-timetable": {
      "command": "node",
      "args": ["C:\\absolute\\path\\db-timetable-mcp\\dist\\index.js"]
    }
  }
}

.env ファイルは現在の作業ディレクトリとプロジェクトディレクトリの隣から検索されます。これにより、Claude Desktop が別の場所からコンパイル済みサーバーを起動する場合にも対応できます。また、MCP エントリーの env オブジェクトで 2 つの認証情報を設定することもできます。

設定を変更した後は、Claude Desktop を完全に終了してから再起動してください。詳しくはトラブルシューティングをご覧ください。

ツール

ツール	目的
getStationBoard	推奨。予定ダイヤとすべての変更内容を結合して、リアルタイムの駅発着案内を作成します
getPlannedTimetable	EVA 番号、日付、時刻に対応する静的な予定ダイヤ
getCurrentTimetable	変更内容全体（fchg）。互換性のため、この名前を使用しています
getRecentChanges	インクリメンタル更新用の直近 2 分間の変更（rchg）
findStations	駅名、EVA 番号、または DS100 コードで駅を検索します

すべてのツールで includeRawXml: true を任意で指定できます。例を含む完全なリファレンスは docs/api.md をご覧ください。

データモデル

到着または出発イベントの略式表記：

{
  "planned": { "time": { "local": "2026-07-17T10:20" }, "platform": "8" },
  "changed": { "time": { "local": "2026-07-17T10:27" }, "platform": "10" },
  "effective": { "time": { "local": "2026-07-17T10:27" }, "platform": "10" },
  "delayMinutes": 7,
  "platformChanged": true,
  "isCancelled": false
}

旅行者に表示する情報には effective を使用してください。モデルは db-timetable://docs/data-model リソースから同じ説明を取得できます。詳しくは docs/data-model.md をご覧ください。

Streamable HTTP と Docker

ローカルで起動します。

MCP_TRANSPORT=http npm start

• MCP エンドポイント：http://127.0.0.1:3000/mcp
• ヘルスチェック：http://127.0.0.1:3000/health

Docker Compose を使用する場合：

docker compose up --build -d
docker compose ps
curl http://127.0.0.1:3000/health

Compose は意図的にポートをループバックにバインドし、非特権ユーザーとして実行し、読み取り専用ファイルシステムを使用します。公開エンドポイントには、リバースプロキシの背後で TLS と認証も必要です。ALLOWED_HOSTS には、許可するすべてのホスト名を指定する必要があります。

設定

変数	デフォルト	説明
DB_TIMETABLE_CLIENT_ID	–	DB クライアント ID。API 呼び出しに必須です
DB_TIMETABLE_CLIENT_SECRET	–	DB API キー。API 呼び出しに必須です
DB_TIMETABLE_BASE_URL	公式の v1 URL	代替のベース URL。主にテスト用です
DB_TIMETABLE_TIMEOUT_MS	15000	リクエストのタイムアウト。1000～120000 ms の範囲で指定します
MCP_TRANSPORT	stdio	stdio または http
HOST	127.0.0.1	HTTP バインドアドレス
PORT	3000	HTTP ポート
MCP_ENDPOINT	/mcp	Streamable HTTP のパス
ALLOWED_HOSTS	–	カンマ区切りのホスト許可リスト。0.0.0.0／:: を使用する場合に必須です
DOTENV_CONFIG_PATH	–	env ファイルの絶対パスを明示的に指定します
LOG_LEVEL	info	debug、info、warn、または error

旧値の TRANSPORT_TYPE=sse|httpStream と SSE_ENDPOINT も Streamable HTTP にマッピングされるため、移行によって既存のクライアントが動作しなくなることはありません。

開発

npm run dev          # stdio with watch mode
npm run dev:http     # Streamable HTTP with watch mode
npm run check        # lint, types, tests, and build
npm run test:coverage

詳しくはこちらをご覧ください。

• API リファレンス
• データモデル
• アーキテクチャ
• テスト戦略
• コントリビューション
• セキュリティポリシー
• 変更履歴

docs/ 内のドキュメントは現在、ドイツ語で書かれています。

トラブルシューティング

Claude Desktop で Expected "," or "]" after array element が表示される

バージョン 2 に更新して、再ビルドしてください。以前のバージョンでは、ログ行が stdio プロトコルのチャネルに書き込まれていました。バージョン 2 では stderr を使用します。

.env が存在するのに DB-API-Zugangsdaten fehlen が表示される（メッセージの意味は「DB API の認証情報がありません」です）

ファイルは package.json の隣にあるリポジトリのルートに配置する必要があります。別の場所にある場合は、DOTENV_CONFIG_PATH に絶対パスを設定してください。値を引用符で囲んだり、末尾に空白を残したりしないでください。

DB API から 401／403 が返される

クライアント ID と API キーが正しい組み合わせであること、またアプリケーションが Timetables 製品をサブスクライブしていることを確認してください。

プラットフォームが間違っている

getStationBoard を使用して、effective.platform を参照してください。planned.platform は定義上、予定されているプラットフォームです。changed.platform は DB から変更が報告された場合にのみ存在します。

データソースとライセンス

時刻表データは Deutsche Bahn から提供され、Timetables API 1.0.274 を通じて配信されます。DB API Marketplace によると、データは CC BY 4.0 の下で提供されているため、使用する際は Deutsche Bahn の表示が必要です。Marketplace では現在、1 分あたり 60 回の呼び出し制限が示されています。

MCP サーバー自体は MIT ライセンスの下で提供されています。