12306 Train Mcp

Name: 12306 Train Mcp
Author: LLM Mart

No install snippet on purpose. A working MCP config is a command, its arguments and an environment block — the last two are where API keys live, so this catalogue never stores them and cannot publish them. Follow the link above for the authors' own instructions.

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 with mcp-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="")