China 12306 Train Tickets MCP

中国 12306 火车票 MCP

从任意 MCP 客户端查询中国铁路 12306 车票余量——按中文车站名称和日期查询列车时刻表及剩余座位。只读，不支持订票，无需账号。

• 30 秒即可试用：免费的公共 MCP 端点已在运行——只需将 URL 粘贴到 MCP 客户端中（无需安装，无需 API 密钥）。
• 也可自行托管：单个 Python 文件，使用标准库 HTTP 和 FastMCP，无需付费依赖。

⚡ 使用托管端点（无需设置）

https://mcp.pianam.cn/train-mcp/mcp

传输方式：Streamable HTTP（兼容 MCP 2025-03-26）。无需身份验证。

🔌 客户端配置

将以下内容添加到 MCP 客户端的 mcpServers 配置中（Claude Desktop 的 claude_desktop_config.json、Cursor 的 mcp.json、Cline、Cherry Studio 等）：

{
  "mcpServers": {
    "12306-train": {
      "type": "http",
      "url": "https://mcp.pianam.cn/train-mcp/mcp"
    }
  }
}

不接受 "type": "http" 的客户端（部分 Cherry Studio / 较旧版本的 Cline）可以使用相同配置项，只需保留 "url"。

🧰 工具

工具	参数	返回内容
query_train_tickets(from_city, to_city, date="")	from_city / to_city：中文城市或车站名称，例如 "青岛"、"北京南"。 date：YYYY-MM-DD；留空时默认为明天。12306 的售票预售期通常为 15 天。	列车列表，包含车次、出发 / 到达车站及时间、历时，以及各席别的剩余座位（商务座 / 一等座 / 二等座、软卧 / 硬卧、硬座、无座）。
search_station(keyword)	keyword：例如 "北京"。	模糊匹配车站名称（最多返回 30 个：北京、北京南、北京西、北京北……），适用于不确定要使用哪个车站的情况。

📡 数据来源、缓存和限制

• 数据来自 12306 自有的公共查询端点（kyfw.12306.cn/otn/leftTicket/...）——仅进行只读查询；此服务无法订票，请通过 12306 官方 App / 网站购票。
• 车站代码表在本地缓存 7 天；车票查询缓存 300 秒。
• 无需 API 密钥，无需登录。
• 托管端点的速率限制为每个 IP 每分钟 200 次请求。

🐢 自行托管

git clone https://github.com/boy-373/12306-train-mcp.git
cd 12306-train-mcp
pip install -r requirements.txt
python train_mcp_server.py
# the server listens on 127.0.0.1:8003 by default; override with:
#   MCP_HOST=0.0.0.0 MCP_PORT=9000 python train_mcp_server.py
#   MCP_ALLOWED_HOSTS="your-domain.com,127.0.0.1:*"
#   MCP_ALLOWED_ORIGINS="https://your-domain.com"

然后将 MCP 客户端指向 http://127.0.0.1:8003/mcp。 始终无需 API 密钥或账号。

🐳 使用 Docker 自行托管

选项 A — 拉取预构建镜像（最快，无需构建）：

docker run -d -p 8000:8000 --name 12306-train-mcp ghcr.io/boy-373/12306-train-mcp:latest

选项 B — 从源代码构建：

git clone https://github.com/boy-373/12306-train-mcp.git
cd 12306-train-mcp
docker build -t 12306-train-mcp .
docker run -d -p 8000:8000 --name 12306-train-mcp 12306-train-mcp

然后将 MCP 客户端指向 http://127.0.0.1:8000/mcp。 容器默认监听 0.0.0.0:8000（可使用 -e MCP_PORT=9000 覆盖，并相应调整 -p）。无需 API 密钥或账号。

• train_stations.json — 内置的 12306 车站名称 → 电报码对照表（每 7 天自动从 12306 刷新）。

🗂️ 文件

• train_mcp_server.py — MCP 服务（FastMCP，Streamable HTTP 传输）。
• rate_limit.py — 轻量级的按 IP 滑动窗口速率限制中间件（默认每分钟 200 次请求）。
• requirements.txt — mcp、uvicorn、starlette。
• server.json — 官方 MCP Registry 清单（远程服务条目，可直接使用 mcp-publisher 发布）。
• smithery.yaml / glama.json — 目录列表元数据。

---

🧯 Parameter guide & common errors (read this if a call fails)

query_train_tickets(from_city, to_city, date="")

Parameter	What to pass	Notes
from_city / to_city	Chinese station or city names, e.g. "青岛", "北京", "上海虹桥"	A city name works when the city has one main station; for multi-station cities use the exact station name. Not sure? Call search_station("北京") first — it returns 北京/北京南/北京西/北京北…
date	YYYY-MM-DD, e.g. "2026-09-20"	Optional — defaults to tomorrow when empty. 12306's pre-sale window is 15 days (dates further out return an error or empty results).

Why you may get an HTTP 400 / error result:

1. Bad date format — must be exactly YYYY-MM-DD (2026/09/20, 2026年9月20日, Sep 20 all fail).
2. Station name not found — typo, pinyin ("qingdao"), or a vague nickname the code table doesn't contain. Fix: call search_station with a keyword and copy the exact name.
3. City-level name for a multi-station city — e.g. "北京" usually resolves to 北京 station, but if you want a specific station pass "北京南" / "北京西" explicitly.
4. Date outside the 15-day pre-sale window — 12306 has not released those tickets yet.

Correct call examples:

query_train_tickets(from_city="青岛", to_city="北京", date="2026-09-20")
query_train_tickets(from_city="北京南", to_city="上海虹桥")        # date omitted -> tomorrow
search_station(keyword="上海")                                   # -> 上海/上海南/上海虹桥/上海西…

A successful response returns 车次总数 plus a 车次 list (train number, departure/arrival station & time, duration, and remaining seats per class). An unrecognized station returns {"error": "出发站「…」无法识别，可用 search_station 工具查车站名"} — simply re-call with the exact name.

---

🧯 参数说明与常见错误（调用失败先看这里）

query_train_tickets(from_city, to_city, date="") 参数说明

参数	填什么	注意
from_city / to_city	中文车站名或城市名，如 "青岛"、"北京"、"上海虹桥"	城市只有一个主车站时填城市名即可；多车站城市建议填具体车站名。不确定时先调 search_station("北京")，会返回 北京/北京南/北京西/北京北 等准确站名
date	YYYY-MM-DD 格式，如 "2026-09-20"	可留空，留空默认查明天；12306 预售期通常为 15 天，超出预售期的日期会查询失败或无结果

返回 400 / 错误结果的常见原因：

1. 日期格式错误：必须严格为 YYYY-MM-DD，2026/09/20、2026年9月20日、Sep 20 等写法都会失败；
2. 站名不存在：错别字、拼音（如 "qingdao"）、或码表中没有的俗称都会无法识别。解决方法：先用 search_station 关键词搜索，复制返回的准确站名；
3. 多车站城市用了城市通称：如 "北京" 一般能匹配到「北京」站，但要去特定车站请明确传 "北京南"、"北京西" 等；
4. 日期超出 15 天预售期：12306 尚未放票，查询会返回失败提示。

正确调用示例：

query_train_tickets(from_city="青岛", to_city="北京", date="2026-09-20")
query_train_tickets(from_city="北京南", to_city="上海虹桥")        # date 留空 -> 默认明天
search_station(keyword="上海")                                   # 返回 上海/上海南/上海虹桥/上海西…

调用成功会返回 车次总数 和 车次 列表（车次号、出发/到达站与时间、历时、各席别余票）；站名无法识别时返回 {"error": "出发站「…」无法识别，可用 search_station 工具查车站名"}，换成准确站名重试即可。

🇨🇳 中文使用说明

一句话：直接用中文站名查 12306 余票，数据来自 12306 官方公开查询接口，纯只读。

在线直连地址（免费、无需 Key、开箱即用）：https://mcp.pianam.cn/train-mcp/mcp

在 MCP 客户端（Claude Desktop / Cursor / Cherry Studio / Cline 等）的配置里加入：

{
  "mcpServers": {
    "12306-train": {
      "type": "http",
      "url": "https://mcp.pianam.cn/train-mcp/mcp"
    }
  }
}

工具：

• query_train_tickets(from_city, to_city, date)：查余票。出发/到达站直接给中文城市或车站名（如「青岛」「北京南」），日期格式 YYYY-MM-DD，留空默认明天；返回车次、出发到达时间、历时及商务座/一等座/二等座/软卧/硬卧/硬座/无座等余票。
• search_station(keyword)：不确定城市有哪些车站时模糊搜索站名（如「北京」返回 北京/北京南/北京西/北京北 等）。
• 仅查票，不能购票；12306 预售期通常 15 天。

服务特性：数据源全部为公开接口、无需注册/付费；服务端内存缓存、失败自动降级/切换备用通道；单 IP 限流 200 次/分钟。

本地部署：

git clone https://github.com/boy-373/12306-train-mcp.git
cd 12306-train-mcp
pip install -r requirements.txt
python train_mcp_server.py
# 默认监听 127.0.0.1:8003，可用环境变量 MCP_HOST / MCP_PORT / MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS 覆盖

Docker 自托管：

# 方式一：直接拉预构建镜像（最快，无需构建）
docker run -d -p 8000:8000 --name 12306-train-mcp ghcr.io/boy-373/12306-train-mcp:latest

# 方式二：从源码构建
git clone https://github.com/boy-373/12306-train-mcp.git && cd 12306-train-mcp
docker build -t 12306-train-mcp .
docker run -d -p 8000:8000 --name 12306-train-mcp 12306-train-mcp
# MCP 地址填：http://127.0.0.1:8000/mcp

容器默认监听 0.0.0.0:8000（可用 -e MCP_PORT=端口 改），无需任何 API Key 或账号。

📄 License

MIT © 2026 boy-373

Install via Smithery

One-click install for Smithery-supported clients (Claude Desktop, Cursor, etc.):

Or run:

npx -y @smithery/cli install 1561852680/12306-train-mcp --client claude

---

🔌 适用于任何 AI 客户端 — 一键式 MCP 网关

我们托管了免费的 MCP 聚合网关：你的 AI 助手（Cherry Studio、Claude Desktop、Cursor、Cline — 任何 MCP 客户端）都可以通过一个 URL 发现并使用 MCP 工具：

https://mcp.pianam.cn/ai/mcp

只需添加一次，之后用自然语言交流即可 — AI 会自动为你搜索 → 检查 → 调用合适的 MCP。

• 🔍 搜索索引中的 22,000+ 个 MCP 服务（中文和英文）
• ⚡ 开箱即用，可直接调用的 50+ 个在线托管 MCP（天气、汇率、热门趋势、IP 地理位置、火车票……）
• 📦 基于 GitHub 的 MCP：搜索结果会提供在本地安装的链接
• ✅ 每周检查服务健康状况 — 正常运行的服务会优先显示
• 🆓 免费使用，无需密钥

📖 3 步设置指南 / 中文接入教程：https://mcp.pianam.cn/ai-gateway