12306 Train Mcp

MCP server for China Railway 12306 ticket availability: schedules and seats by Chinese station name.

LLM Mart 9 views 165 listing impressions

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

From the project's README.

Related servers

Read and write RAGE Package Format archives

23 views

See how ChatGPT, Claude, Gemini and Perplexity read any website. Scored out of 100.

19 views

MCP server for Geargrafx PC Engine / TurboGrafx-16 emulator

19 views

Read-only on-chain intel for AI agents on Base: balances, tokens, gas, tx status. No API keys.

15 views