12306 Train Mcp
MCP server for China Railway 12306 ticket availability: schedules and seats by Chinese station name.
Query China Railway 12306 ticket availability from any MCP client — train schedules and remaining seats by Chinese station name and date. Read-only, no booking, no account.
- Try it in 30 seconds: a free public MCP endpoint is already running — just paste the URL into your MCP client (no install, no API key).
- Or self-host: a single Python file, stdlib HTTP + FastMCP, zero paid dependencies.
⚡ Use the hosted endpoint (no setup)
https://mcp.pianam.cn/train-mcp/mcp
Transport: Streamable HTTP (MCP 2025-03-26 compatible). No authentication required.
🔌 Client configuration
Add this to your MCP client's mcpServers configuration (Claude Desktop claude_desktop_config.json, Cursor mcp.json, Cline, Cherry Studio, etc.):
{
"mcpServers": {
"12306-train": {
"type": "http",
"url": "https://mcp.pianam.cn/train-mcp/mcp"
}
}
}
Clients that do not accept
"type": "http"(some Cherry Studio / older Cline versions) accept the same entry with just"url".
🧰 Tools
| Tool | Parameters | Returns |
|---|---|---|
query_train_tickets(from_city, to_city, date="") |
from_city / to_city: Chinese city or station names, e.g. "青岛", "北京南".date: YYYY-MM-DD; empty defaults to tomorrow. 12306's booking window is usually 15 days. |
Train list with train number, departure/arrival stations & times, duration, and remaining seats per class (business/first/second class, soft/hard sleeper, hard seat, no-seat). |
search_station(keyword) |
keyword: e.g. "北京". |
Fuzzy-matches station names (returns up to 30: 北京, 北京南, 北京西, 北京北 …) when you are not sure which station to use. |
📡 Data sources, caching & limits
- Data comes from 12306's own public query endpoints (
kyfw.12306.cn/otn/leftTicket/...) — read-only queries only; this server cannot book tickets, please buy via the official 12306 app/website. - Station code table cached locally for 7 days; ticket queries cached for 300 seconds.
- No API key, no login required.
- The hosted endpoint is rate-limited to 200 requests / minute / IP.
🐢 Self-hosting
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"
Then point your MCP client at http://127.0.0.1:8003/mcp.
No API keys or accounts are ever required.
🐳 Self-host with Docker
Option A — pull the pre-built image (fastest, no build):
docker run -d -p 8000:8000 --name 12306-train-mcp ghcr.io/boy-373/12306-train-mcp:latest
Option B — build from source:
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
Then point your MCP client at http://127.0.0.1:8000/mcp.
The container listens on 0.0.0.0:8000 by default (override with -e MCP_PORT=9000 and adjust -p accordingly). No API keys or accounts required.
train_stations.json— bundled 12306 station name → telegraph-code table (auto-refreshed from 12306 every 7 days).
🗂️ Files
train_mcp_server.py— the MCP server (FastMCP, Streamable HTTP transport).rate_limit.py— lightweight per-IP sliding-window rate-limit middleware (200 req/min default).requirements.txt—mcp,uvicorn,starlette.server.json— official MCP Registry manifest (remote server entry, ready to publish withmcp-publisher).smithery.yaml/glama.json— directory listing metadata.
🧯 Parameter guide & common errors (read this if a call fails)
query_train_tickets(from_city, to_city, date="")
From the project's README.