12306 MCP Server

社区

基于 MCP 的 12306 火车票实时查询服务

分类: 其他第 30 / 230
Stars: ★ 416 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Python 3.10+ · Docker
凭据: 无需凭据
许可证: MIT
最近提交: 33 天前
工具数: 7

66FMRS · C

这是一个 MIT 许可的第三方开源 MCP 服务端，把 12306 的公开查询能力（余票、票价、车站、经停、换乘、时间）标准化为 7 个 MCP 工具，支持 Stdio 与 Streamable HTTP 双传输并提供 Docker 部署，还内置了 /health、/schema/tools 等运维端点，工程结构清晰、文档较完整。它并非 12306 官方产品，也不提供购票类操作，且作者明确声明仅供学习研究、禁止商业使用，因此适合个人出行查询与 MCP 开发学习，不适合作为有 SLA 要求的商业系统。

最强项 · 文档质量 15/20 最弱项 · 可靠性 11/20

可靠性

11/20

安全与权限

13/20

维护活跃度

13/20

文档质量

15/20

安装易用性

14/20

查看各项评分依据

可靠性 11/20: 证明材料仅限 README 与 server.json，均属不可执行证据，未提供任何 CI 工作流或已提交测试；静态评审规则明确规定缺乏可验证执行证据时 reliability 不超过 12。正面信号：Manifest 声明 PyPI 单一包、stdio 传输、版本号与 README 一致，工具清单（query-tickets、query-ticket-price、search-stations、query-transfer、get-train-route-stations、get-train-no-by-train-code、get-current-time）与 README 表格对应清晰，README 说明架构上 server.py 传输无关、stdio 与 HTTP 复用同一实例、Schema 单一来源于 ticket_service.MCP_TOOLS。扣分点：完全没有测试、CI、错误码或失败场景说明，官方 12306 接口变动导致的脆弱性无缓解证据，已加载车站数、会话数等运行时事实无法从文件核实，7 个工具的实际返回结构与参数边界未经证实，故只给 11 分。
安全与权限 13/20: 无红线行为：未发现恶意代码、凭据窃取、隐蔽外传、不可逆删除/支付/部署默认动作或伪造身份。工具为只读查询（余票、票价、车站、换乘、经停、车次号、时间），无写操作、无支付、无确认要求，本身权限暴露较小。风险与扣分点：全部流量指向 12306 外部接口，属未授权第三方数据抓取，服务端可能触发限流、封禁或 IP 风控，README 免责声明自陈可能被账号封禁；无任何鉴权、速率限制、缓存或审计说明；HTTP 模式默认绑定 SERVER_HOST=0.0.0.0 并暴露 /mcp、/health、/schema/tools，若部署于公网则无认证即为任意调用面；输入校验与 SSRF/注入面未见文档化；无隐私与数据流向声明，README 仅笼统称不存储不篡改。因属低敏感只读场景但边界与确认机制不完整，给 13 分。
维护活跃度 13/20: 有 MIT 许可证，server.json 声明版本 0.5.0.post20260822，README 有 PyPI、Docker、GitHub 徽章及发布命令（build + twine upload），说明存在发布流程；仓库非归档，386 stars、仅 1 个 open issue，采用 uv.lock 锁依赖、pydantic-settings 配置、mypy 严格模式与 black/isort 格式化规范，展现一定工程纪律。扣分点：无法从静态材料验证提交频率、issue 响应时效、依赖更新节奏、发布者身份真实性、安全响应渠道或贡献者治理；无 SECURITY.md、无 CHANGELOG、无 CI 记录；版本号含未来日期样式（post20260822）可疑但无法证实；亦无明确安全通报入口。综合给 13 分。
文档质量 15/20: 文档层次相当完整：README 含功能特性表、三种部署方式（Stdio、Streamable HTTP、Docker）、7 个工具及必填参数表、环境变量配置表（SERVER_HOST/SERVER_PORT/DEBUG/LOG_LEVEL）、项目结构树、开发指南与免责声明，另有 docs/ 下 6 份工具详情文档声称覆盖参数、返回示例与调用方式。扣分点：未提供工具返回结构示例、错误码与故障排查章节、速率/配额与成本说明；鉴权与数据流向披露缺失；详细文档内容未在证据中给出，无法确认真实性；配置默认 0.0.0.0 未伴随安全部署提示。按“可用但存在隐含假设与排查空白”定位，给 15 分。
安装易用性 14/20: 安装路径清晰且多样：uvx mcp-server-12306 一行启动，或 pip/pipx，Docker 一行 docker run -p 8000:8000，另有源码 uv sync 与 scripts/start_server.py；README 给出 Claude Desktop 风格 stdio 配置、Streamable HTTP 的 url 配置以及 Docker 自定义端口与环境变量示例，环境要求明确（Python >=3.10,<3.14、uv 推荐、需可达 12306）。扣分点：静态评审下未实际验证安装是否成功，Packaging 声明与实现一致性无法核实；HTTP 模式需自行处理端口、部署与安全边界；Docker 镜像标签与 PyPI 版本是否同步未知；缺少 Windows 平台与常见失败（代理、网络受限）的排查指引。按“可工作但依赖手动与外部网络条件”定位，给 14 分。

静态评测 · 未实际运行收录于 2026-09-18

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络

适合谁

需要在中国境内做火车出行规划的个人用户
希望把 12306 查询能力接入 Claude Desktop、Cursor 等 MCP 客户端的开发者
需要自建远程 HTTP MCP 服务或使用 Docker 部署的团队
用于学习与研究 MCP 服务端实现的开发者

不适合谁

需要官方购票、改签、退票或支付能力的场景（本项目仅提供查询）
商业用途或对可用性、稳定性有 SLA 要求的正式生产系统
对上游接口波动零容忍、要求数据绝对实时的关键业务
期望获得 12306 官方支持与背书的用户

所需权限

网络访问权限：需可访问 12306 官方接口
本地文件读取：读取内置车站数据等静态资源
HTTP 模式下的端口监听：默认绑定 0.0.0.0:8000
读取项目根目录 .env 文件（若使用）

风险与副作用

第三方非官方项目，仅聚合与转发 12306 公开接口，上游接口变更或限流可能导致查询失败
README 明确声明仅供学习研究，严禁商业用途；使用造成的后果由使用者承担
以 0.0.0.0 暴露 HTTP 端口可能被同网络其他主机访问，且项目未描述任何鉴权机制
频繁调用上游接口可能触发限流，甚至影响使用者账号
查询结果依赖上游数据，可能存在延迟或不准确，不应作为唯一决策依据

安装接入

准备工作

运行环境：Python 3.10+ · Docker

其他可选配置项（4 个）

SERVER_HOST 可选 HTTP 监听地址，默认 0.0.0.0，仅远程 HTTP 模式需要，通过环境变量或 .env 设置。

SERVER_PORT 可选 HTTP 监听端口，默认 8000，仅远程 HTTP 模式需要。

DEBUG 可选调试模式开关，默认 false，可选。

LOG_LEVEL 可选日志级别（DEBUG/INFO/WARNING/ERROR），默认 INFO，可选。

准备环境：Python >= 3.10, < 3.14，并确保可访问 12306 官方接口。
Stdio 模式（本地客户端推荐）：执行 uvx mcp-server-12306，或在客户端配置中写入 {"mcpServers": {"12306": {"command": "uvx", "args": ["mcp-server-12306"]}}}；也可使用 pip / pipx 安装。
Streamable HTTP 模式：安装后运行 mcp-12306，或从源码运行 uv run python scripts/start_server.py，服务默认监听 8000 端口，客户端配置 URL 为 http://localhost:8000/mcp。
Docker 部署：docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest。
可选配置：通过环境变量或 .env 设置 SERVER_HOST（默认 0.0.0.0）、SERVER_PORT（默认 8000）、DEBUG（默认 false）、LOG_LEVEL（默认 INFO）。

claude_desktop_config.json

{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "12306": {
      "command": "uvx",
      "args": [
        "mcp-server-12306"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add 12306 -- uvx mcp-server-12306

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

在客户端工具列表中应能看到 query-tickets、search-stations 等 7 个工具；连接后发送“搜索车站北京”应返回车站数据，说明安装成功。

常见排障

确认 Python 版本满足 >= 3.10, < 3.14
确认运行环境可正常访问 12306 官方接口
Stdio 模式下检查客户端配置中的命令与参数是否正确（uvx / pipx / uv）
HTTP 模式下访问 /health 检查服务状态、已加载车站数与活跃会话数
HTTP 模式下访问 /schema/tools 核对工具 Schema 是否正常加载
端口冲突时通过 SERVER_PORT 调整监听端口，并用 DEBUG 与 LOG_LEVEL=DEBUG 提升日志详细程度
车站数据异常时可运行 scripts/update_stations.py 更新车站数据

试试这样问

连接成功后，可以直接对 AI 助手这样说：

查询明天北京到上海的高铁余票
搜索车站“杭州东”，返回三字码
查一下 G1 次列车沿途所有经停站和到发时刻
帮我查后天从广州到长沙的中转换乘方案

工具能力 7

query-tickets 只读

余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤

query-ticket-price 只读

实时查询各车次各席别票价

search-stations 只读

车站模糊搜索，支持中文 / 拼音 / 简拼 / 三字码

query-transfer 只读

中转换乘方案查询，返回完整路径与等待时间

get-train-route-stations 只读

查询指定列车的全部经停站与到发时刻

get-train-no-by-train-code 只读

由车次号获取官方唯一编号

get-current-time 只读

获取当前时间与相对日期，辅助选择出行日期

使用场景

在 AI 助手中对话式查询指定日期、区间的火车余票与座席情况

对比同一线路各车次各席别的实时票价

按中文、拼音、简拼或三字码搜索全国车站

在没有直达车时查询官方中转换乘方案

查询某趟列车的全部经停站与到发时刻

获取当前时间与相对日期，辅助确定出行日期

支持客户端

Claude Desktop

Cursor

依据项目文档列出，未经本站实测。

详细介绍

12306 MCP Server 是一个基于 Model Context Protocol (MCP) 的高性能火车票查询后端系统，通过标准化接口转发 12306 官方公开数据，提供余票、票价、车站、经停、换乘与时间六大类查询能力。项目为 MIT 许可的第三方开源项目，并非 12306 官方产品。它同时支持 Stdio（本地客户端）与 Streamable HTTP（远程部署，默认 8000 端口）两种传输模式，两者共享同一核心实例，并提供 Docker 镜像部署方式。