Mcp Server 12306

io.github.drfccv由 GitHub 帳號 drfccv 發布v0.3.1更新於 Oct 24, 2026

An MCP server that provides 12306 ticket query

概覽

AI 產生的概覽

提供 12306 火車票查詢的 MCP 伺服器,讓助理查詢剩餘車票、票價、車站、轉乘與時刻資訊。

可以做什麼
  • 依路線與日期查詢剩餘車票、車次、座席與發車時刻
  • 即時查詢各車次各席別票價
  • 以中文、拼音、簡拼或三字碼模糊搜尋全國車站
  • 查詢官方轉乘方案,以及指定列車的全部停靠站與到開時刻
  • 將車次號轉為官方唯一編號,並取得目前時間或相對日期以協助選擇出行日期
適用情境
適合在中國規劃鐵路行程時使用,讓助理直接查看剩餘車票、票價、車站名稱、轉乘方案或停靠站,不必開啟 12306 網站或應用程式。
執行需求
以本機 Python 套件形式執行(Python 3.10 至 3.14 以下),可透過 uvx、pip 或 pipx 安裝,也可使用 Docker 映像。需要能連線 12306 官方介面的網路。SERVER_HOST、SERVER_PORT、DEBUG、LOG_LEVEL 等環境變數僅適用於 HTTP 模式。
安裝前請注意
README 聲明本專案僅供學習研究、嚴禁商用,使用造成的後果(包括帳號停權、法律風險等)由使用者自行承擔。它會將請求轉送到 12306 官方介面,查詢資料會傳送給第三方。HTTP 模式預設監聽 0.0.0.0,若未修改 SERVER_HOST 會暴露於網路上。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Mcp Server 12306,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

🚄 MCP Server 12306

基于 Model Context Protocol (MCP) 的 12306 火车票查询服务

[PyPI - Version] [PyPI - Downloads] [Python - 3.10+] [Docker - Pulls] [License - MIT] [MCP - SDK v2] [Transport - Stdio/HTTP] [GitHub - Stars]


支持 余票 / 票价 / 车站 / 经停 / 换乘 / 时间 六大查询能力,开箱即用,适配 AI 助手、自动化脚本、智能终端等场景。


📑 目录


✨ 功能特性

类别能力
🎫 余票查询余票 / 车次 / 座席 / 时刻一站式查询,支持按车次过滤
💰 票价查询实时查询各车次各席别票价(商务座 → 无座全覆盖)
🏙️ 车站搜索全国 3382+ 车站,支持中文 / 拼音 / 简拼 / 三字码模糊搜索
🔄 中转换乘官方换乘方案自动分页抓取,返回完整路径与等待时间
🛤️ 经停查询查询指定列车全部经停站与到发时刻
🕐 时间工具获取任意时区当前时间、相对日期计算,辅助选择出行日期
🔌 双传输模式Stdio(本地)| Streamable HTTP(远程),同一核心实例共享
🔄 协议自动协商基于 MCP SDK v2,自动兼容握手时代(2025-11-25)与现代协议(2026-07-28)

🚀 快速开始

环境要求

依赖要求
Python>= 3.10, < 3.14
包管理器uv(推荐)或 pip / pipx
网络可访问 12306 官方接口

💡 推荐使用 uv:环境隔离、安装快、锁文件管理依赖版本。

方式一:Stdio 模式(本地客户端推荐)

MCP Server 通过标准输入/输出与客户端通信,不占用网络端口,适合 Claude Desktop、Cursor 等本地 MCP 客户端。

安装:

bash
# uvx(推荐,环境隔离)uvx mcp-server-12306
# 或 pip / pipxpip install mcp-server-12306

客户端配置(如 claude_desktop_config.json):

json
{  "mcpServers": {    "12306": {      "command": "uvx",      "args": ["mcp-server-12306"]    }  }}
其他安装方式(点击展开)

pipx:

json
{  "mcpServers": {    "12306": {      "command": "pipx",      "args": ["run", "--no-cache", "mcp-server-12306"]    }  }}

本地源码(开发者调试):

bash
git clone https://github.com/drfccv/mcp-server-12306.gitcd mcp-server-12306uv sync
json
{  "mcpServers": {    "12306": {      "command": "uv",      "args": ["--directory", "/path/to/mcp-server-12306", "run", "mcp-server-12306"]    }  }}

方式二:Streamable HTTP 模式(远程部署)

Server 启动 Web 服务(默认 8000 端口),通过 MCP Streamable HTTP 协议通信:POST 发送 JSON-RPC、GET 订阅流式响应、DELETE 结束会话。

启动:

bash
# 安装后直接启动mcp-12306
# 或本地源码启动uv run python scripts/start_server.py

客户端配置:

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

内置 HTTP 端点:

端点方法说明
/mcpPOST / GET / DELETEMCP Streamable HTTP 协议入口
/healthGET健康检查(含已加载车站数、活跃会话数)
/schema/toolsGET全部工具 JSON Schema
/GET服务信息(版本、协议版本、端点)

方式三:Docker 部署

bash
# 拉取镜像并运行(默认端口 8000)docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest
# 自定义端口docker run -d -p 8080:8000 \  -e SERVER_HOST=0.0.0.0 \  -e SERVER_PORT=8000 \  --name mcp-server-12306 \  drfccv/mcp-server-12306:latest

🛠️ 工具一览

工具名功能必填参数
query-tickets余票 / 车次 / 座席 / 时刻一站式查询from_station、to_station、train_date
query-ticket-price实时查询车次票价from_station、to_station、train_date
search-stations车站模糊搜索(中文 / 拼音 / 简拼 / 三字码)query
query-transfer中转换乘方案查询from_station、to_station、train_date
get-train-route-stations查询列车经停站及时刻表train_no、from_station、to_station、train_date
get-train-no-by-train-code车次号 → 官方唯一编号train_code、from_station、to_station、train_date
get-current-time当前时间与相对日期(辅助选日期)无

📖 每个工具的参数说明、返回示例、调用示例详见 📚 详细文档。


⚙️ 配置项

通过环境变量或项目根目录 .env 文件配置:

环境变量默认值说明
SERVER_HOST0.0.0.0HTTP 监听地址
SERVER_PORT8000HTTP 监听端口
DEBUGfalse调试模式
LOG_LEVELINFO日志级别(DEBUG / INFO / WARNING / ERROR)
bash
# 示例:.envSERVER_HOST=127.0.0.1SERVER_PORT=8000LOG_LEVEL=INFO

🏗️ 项目结构

mcp-server-12306/├── src/mcp_12306/            # 主包│   ├── server.py             # 核心 Server(工具注册与分发,双传输共享)│   ├── stdio_server.py       # Stdio 传输层 + CLI 入口│   ├── http_server.py        # Streamable HTTP 传输层 + HTTP 端点│   ├── services/             # 业务逻辑│   │   ├── station_service.py    # 车站数据服务(加载/搜索/编码转换)│   │   └── ticket_service.py     # 票务查询核心(7 个工具实现)│   ├── utils/                # 配置与日期工具│   │   ├── config.py             # pydantic-settings 配置│   │   └── date_utils.py         # 日期校验工具│   └── resources/            # 静态资源(车站数据 station_name.js)├── scripts/                  # 运维脚本│   ├── start_server.py       # HTTP 模式一键启动(环境自检)│   └── update_stations.py    # 更新车站数据├── docs/                     # 工具详细文档├── pyproject.toml            # 项目元数据 / 依赖 / 构建配置├── Dockerfile                # 多阶段构建(python:3.12-alpine)├── server.json               # MCP 注册表元数据└── uv.lock                   # 依赖锁文件

🧑‍💻 开发指南

bash
# 1. 克隆并初始化git clone https://github.com/drfccv/mcp-server-12306.gitcd mcp-server-12306uv sync
# 2. 类型检查(mypy,严格模式)uv run mypy src scripts
# 3. 代码格式化uv run black src scriptsuv run isort src scripts
# 4. 构建与发布uv run python -m builduv run twine upload dist/*

架构要点:

  • server.py 是传输无关的核心模块——工具注册(TOOL_HANDLERS)与业务分发(call_tool)都在此,stdio 与 HTTP 复用同一实例,保证两种模式行为完全一致。
  • 工具 Schema 单一来源于 ticket_service.MCP_TOOLS,HTTP 的 /schema/tools 端点与 MCP 工具列表同源。
  • 网络请求统一走 _request_with_retry(自动重试 + init 会话保持),业务错误与网络错误分离处理。

📚 详细文档

文档内容
query_tickets.md余票 / 车次 / 座席 / 时刻一站式查询
query_ticket_price.md实时票价查询
search_stations.md车站智能搜索
query_transfer.md中转换乘方案
get_train_route_stations.md列车经停站查询
get_current_time.md当前时间与相对日期

每份文档均包含:功能说明、实现方法、请求参数、返回示例与典型调用方式。


⚠️ 免责声明

  • 本项目仅供学习、研究与技术交流,严禁用于任何商业用途。
  • 本项目仅作为官方公开接口的智能聚合与转发。
  • 使用本项目造成的任何后果(包括但不限于账号封禁、数据异常、法律风险等)均由使用者本人承担,项目作者不承担任何责任。
  • 请遵守中国法律法规及 12306 官方相关规定,合理合规使用。

📄 License

MIT © Drfccv


⭐ 如果这个项目对你有帮助,欢迎 Star 支持!

來源:README.md,提交 413e3cb

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.3.1最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分