← Back to directory
1

12306 MCP Server

Community
MCP server for real-time 12306 train ticket queries
GitHub source repository ↗
★ 386 Stars Category · Other Very popular
66FMRS · C

This is an MIT-licensed third-party open-source MCP server that turns 12306's public query capabilities (availability, prices, stations, stopovers, transfers, time) into 7 MCP tools. It supports both Stdio and Streamable HTTP transports, offers a Docker image, and ships operational endpoints such as /health and /schema/tools, with a clean project layout and fairly complete documentation. It is not an official 12306 product and offers no booking operations, and the author states it is for learning and research with commercial use prohibited, making it a good fit for personal trip lookups and MCP development practice but unsuitable as a commercial system with SLA requirements.

Reliability
11/20
Security and permissions
13/20
Maintenance
13/20
Documentation
15/20
Setup experience
14/20
Read the FMRS scoring method →

12306 MCP Server is a high-performance train ticket query backend built on the Model Context Protocol (MCP). Through standardized interfaces it relays the official 12306 public data and exposes six query domains: remaining tickets, ticket prices, stations, train stopovers, transfers, and time. It is a third-party MIT-licensed open-source project, not an official 12306 product. It supports both Stdio transport for local clients and Streamable HTTP for remote deployment (default port 8000), with both transports sharing the same core instance, and it can also be deployed via Docker.

Tools

query-tickets
One-stop query of remaining tickets, train numbers, seat classes and times, with optional train filtering
query-ticket-price
Real-time query of ticket prices per train and seat class
search-stations
Fuzzy station search by Chinese name, pinyin, initials or three-letter code
query-transfer
Transfer/connection plan query returning the full route and waiting time
get-train-route-stations
Query all stopover stations and arrival/departure times for a train
get-train-no-by-train-code
Map a train code to its official unique train number
get-current-time
Get the current time and relative dates to help pick a travel date

Setup

  1. Prepare the environment: Python >= 3.10, < 3.14, with network access to the official 12306 endpoints.
  2. Stdio mode (recommended for local clients): run uvx mcp-server-12306, or add {"mcpServers": {"12306": {"command": "uvx", "args": ["mcp-server-12306"]}}} to your client config; pip / pipx installs are also supported.
  3. Streamable HTTP mode: run mcp-12306 after installation, or uv run python scripts/start_server.py from source; the server listens on port 8000 by default and the client URL is http://localhost:8000/mcp.
  4. Docker deployment: docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest.
  5. Optional configuration: set SERVER_HOST (default 0.0.0.0), SERVER_PORT (default 8000), DEBUG (default false), LOG_LEVEL (default INFO) via environment variables or a .env file.
claude_desktop_config.json
{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

Fit and risk

Best for

  • Individuals planning train travel within China
  • Developers who want 12306 query capabilities inside MCP clients such as Claude Desktop or Cursor
  • Teams that need a self-hosted remote HTTP MCP service or Docker deployment
  • Developers studying MCP server implementations

Not for

  • Scenarios needing official booking, rebooking, refunds or payment (this project is query-only)
  • Commercial use or production systems with availability/SLA requirements
  • Mission-critical workloads that cannot tolerate upstream API changes or volatility
  • Users expecting official 12306 support or endorsement

Required permissions

  • Network access: must be able to reach the official 12306 endpoints
  • Local file reads: loads bundled static resources such as station data
  • HTTP mode port binding: listens on 0.0.0.0:8000 by default
  • Reads a .env file in the project root when used

Risks and side effects

  • Unofficial third-party project that only aggregates and relays 12306 public endpoints; upstream changes or rate limits can break queries
  • The README explicitly states it is for learning and research only and prohibits commercial use; users bear the consequences of use
  • Binding HTTP to 0.0.0.0 may expose the port to other hosts on the network, and no authentication mechanism is described
  • Frequent upstream calls may trigger rate limiting or affect the user's account
  • Results depend on upstream data and may be delayed or inaccurate, so they should not be the sole basis for decisions

Troubleshooting

  1. Verify Python is >= 3.10, < 3.14
  2. Verify the host can reach the official 12306 endpoints
  3. In Stdio mode, check that the command and args in the client config are correct (uvx / pipx / uv)
  4. In HTTP mode, call /health to check service status, loaded station count and active sessions
  5. In HTTP mode, call /schema/tools to confirm tool schemas load correctly
  6. On port conflicts, change SERVER_PORT and raise verbosity with DEBUG and LOG_LEVEL=DEBUG
  7. If station data looks wrong, run scripts/update_stations.py to update it

Use cases

Conversationally query train availability and seat classes for a given date and route in an AI assistant
Compare real-time prices across trains and seat classes for the same route
Search 3382+ stations by Chinese name, pinyin, initials or three-letter code
Find official transfer plans when no direct train exists
Inspect all stopover stations and arrival/departure times of a specific train
Get the current time and relative dates to help choose a travel date

Supported clients

Claude DesktopFull support
CursorFull support