MCP Server 12306

🚄 12306 MCP Server

12306 MCP Serverは、Model Context Protocol (MCP)に基づく高性能の鉄道切符照会バックエンドです。公式12306の残り切符、駅、経由駅、乗り換え照会や、スマートな時間ツールをサポートしており、AI/自動化/スマートアシスタントなどのシーンに適合しています。インターフェースが使いやすく、簡単に統合でき、すぐに使えます。

🚀 クイックスタート

環境要件

• Python 3.10+
• uv（推奨パッケージマネージャー）

ローカルでのワンクリックデプロイ

# プロジェクトをクローンする
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306

# 依存関係をインストールする
uv sync

# 駅情報を更新する（最初に実行する必要があります）
uv run python scripts/update_stations.py

# サーバーを起動する
uv run python scripts/start_server.py

Dockerデプロイ

# すでに構築されたイメージを直接取得する
 docker pull drfccv/mcp-server-12306:latest

# コンテナを実行する（ポート8000をマッピングする）
 docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

カスタム開発やローカルでの修正後にパッケージ化する場合は、以下のコマンドで独自にイメージを構築できます。

docker build -t drfccv/mcp-server-12306:latest .

設定

.env.exampleを.envにコピーし、必要に応じて変更します。

cp .env.example .env

✨ 主な機能

• リアルタイムの残り切符/列車番号/座席/時刻/乗り換えのワンストップ照会
• 全国の駅情報管理と曖昧検索
• 公式の経由駅、一度の乗り換え案を完全にサポート
• スマートな時間ツールで、相対日付の計算をサポートし、日付入力ミスを防ぐ
• Streamable HTTP伝送プロトコルで、MCP 2025-03-26標準をサポート
• FastAPIの非同期高性能で、秒単位の応答
• MCP標準で、AI/自動化シーンに即座に使用可能

💻 使用例

基本的な使用法

{
  "mcpServers": {
    "12306": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

サポートされるメインフローツール

📚 ドキュメント

このプロジェクトのすべてのメインフローツールの詳細な機能、実装方法、使用方法は、ディレクトリに収録されています。

• query_tickets.md — 残り切符/列車番号/座席/時刻のワンストップ照会
• search_stations.md — 駅の曖昧検索
• get_station_info.md — 駅の詳細情報を取得する
• query_transfer.md — 一度の乗り換え案
• get_train_route_stations.md — 列車の経由駅を照会する
• get_current_time.md — 現在の時間と相対日付を取得する

各ドキュメントには以下が含まれています。

• ツールの機能説明
• 実装方法
• リクエストパラメータと返却例
• 典型的な呼び出し方法

二次開発や統合を行う場合は、対応するツールのドキュメントを読むことをおすすめします。

🔧 技術詳細

ディレクトリ構造

src/mcp_12306/    # メインソースコード
  ├─ server.py    # FastAPIのメインエントリー
  ├─ services/    # ビジネスロジック（切符/駅/HTTP）
  ├─ models/      # データモデル
  ├─ utils/       # ツールと設定
scripts/          # 起動とデータスクリプト

テスト

uv run pytest

📦 インストール

• イメージレポジトリ：drfccv/mcp-server-12306
• イメージを取得する：

  docker pull drfccv/mcp-server-12306:latest
  

• イメージを実行する：

  docker run -d -p 8000:8000 --name 12306-mcp-server drfccv/mcp-server-12306:latest
  

📄 ライセンス

MIT License

⚠️ 重要提示

⚠️ 重要提示

このプロジェクトは学習、研究、技術交流のためのみに使用され、商業目的での使用は厳禁です。 このプロジェクトは12306の公式データを保存、改ざん、伝播することはなく、公式の公開インターフェイスのスマートな集約と転送のみを行います。 このプロジェクトの使用によって生じるすべての結果（アカウントの凍結、データの異常、法的なリスクなどを含むがこれらに限定されない）は、使用者自身が責任を負い、プロジェクトの作者は一切の責任を負いません。 中国の法律と規制および12306の公式規定を遵守し、適切かつ合法的に使用してください。