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/自動化場景即插即用

💻 使用示例

基礎用法

MCP 客戶端配置示例

{
  "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 — 獲取當前時間與相對日期

每個文檔包含：

• 工具功能說明
• 實現方法
• 請求參數與返回示例
• 典型調用方式

如需二次開發或集成，建議先閱讀對應工具的文檔。

📄 許可證

MIT License

⚠️ 免責聲明

⚠️ 重要提示

• 本項目僅供學習、研究與技術交流，嚴禁用於任何商業用途。
• 本項目不存儲、不篡改、不傳播任何 12306 官方數據，僅作為官方公開接口的智能聚合與轉發。
• 使用本項目造成的任何後果（包括但不限於賬號封禁、數據異常、法律風險等）均由使用者本人承擔，項目作者不承擔任何責任。
• 請遵守中國法律法規及 12306 官方相關規定，合理合規使用。

🤖 API & 工具一覽

支持的主流程工具

🧩 目錄結構

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