MCP Server 12306
An MCP server for searching Chinese train tickets on 12306: availability, fares, stations, transfers and stops
- 415 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The server calls the official 12306 interfaces and retries requests on failures
- In HTTP mode it listens on all interfaces by default: `SERVER_HOST` is 0.0.0.0 and the port is 8000
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mcp-server-12306Detects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server calls the official 12306 interfaces and retries requests on failures
- In HTTP mode it listens on all interfaces by default: `SERVER_HOST` is 0.0.0.0 and the port is 8000
This is third-party code. Review the repository files before installing.
What it does
The MCP server gives an agent search over Chinese rail tickets through the official 12306 interfaces. The `query-tickets` tool returns seat availability, trains, seat classes and timetables in one request and accepts a filter by train number. `query-ticket-price` returns live fares per seat class, from business class to standing places. `search-stations` finds stations by Chinese name, pinyin, short pinyin or three-letter code, across at least 3382 stations. `query-transfer` assembles the official transfer options, paging through them in full, and returns the route with waiting times. `get-train-route-stations` lists every stop of a train with arrival and departure times, `get-train-no-by-train-code` converts a train number into the official train ID, and `get-current-time` helps with dates by returning the current time in any time zone and computing relative dates. The server runs as a stdio process through uvx, as an HTTP service over Streamable HTTP, or in Docker. HTTP mode listens on port 8000 and serves `/mcp`, `/health` and `/schema/tools`.
Who it is for. For people planning trips around China or building a travel assistant who want timetables, availability and fares from 12306 right in an agent conversation.
Good fit when
- You plan a trip around China and ask the agent to find trains and ticket availability between cities on a date
- You need to compare fares across seat classes for a given train: `query-ticket-price`
- No direct trains exist and you need transfers: `query-transfer` returns the official options with waiting times
- You need to know where a train stops and when it arrives: `get-train-route-stations`
- You only know a station in pinyin or by code: `search-stations` searches by any of those
Not a fit when
- You need to buy or book a ticket: the tools are queries only
- You need trains outside China: the data comes from 12306
- You want to build the project into a commercial service: the author forbids commercial use
- The environment supports neither Python 3.10–3.13 nor Docker
Example request
Find trains from Beijing to Shanghai for the coming Friday and show availability and fares by seat classMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
`SERVER_HOST`- Address the HTTP mode listens on, 0.0.0.0 by default.
`SERVER_PORT`- HTTP mode port, 8000 by default.
`DEBUG`- Debug mode, off by default.
`LOG_LEVEL`- Log level: DEBUG, INFO, WARNING or ERROR, INFO by default.
Limitations
- Python 3.10 to 3.13 and network access to the official 12306 interfaces are required. Whether the service is reachable from your network depends on 12306 itself.
- The tools only read data: there are no purchases, bookings or account login.
- The author permits use for learning, research and technical exchange and forbids commercial use. Consequences, including account blocking, fall on the user.
- The server does not store or alter 12306 data; it only gathers and forwards responses from the public interfaces.
- The project documentation is written in Chinese, so parameter descriptions have to be read in translation.
How to disable. Remove the 12306 entry from the MCP client configuration. Stop the Docker container with `docker stop mcp-server-12306` and remove it with `docker rm mcp-server-12306`, and uninstall the PyPI package with `pip uninstall mcp-server-12306`.
FAQ
How do I connect 12306 MCP to Claude Desktop?
Add a 12306 server to `claude_desktop_config.json` with command uvx and argument `mcp-server-12306`. Stdio mode occupies no network port and suits Claude Desktop and Cursor. Instead of uvx you can use pipx or install the package with `pip install mcp-server-12306`.
How does stdio differ from HTTP mode?
In stdio mode the client launches the server itself and talks over standard input and output. HTTP mode starts with the `mcp-12306` command as a web service on port 8000, and the client is pointed at `http://localhost:8000/mcp`. `SERVER_HOST`, `SERVER_PORT`, `DEBUG` and `LOG_LEVEL` configure it.
Which parameters does a ticket search need?
`query-tickets`, `query-ticket-price` and `query-transfer` need the departure station `from_station`, the arrival station `to_station` and the date `train_date`. `get-train-route-stations` also needs `train_no`, the train number obtainable through `get-train-no-by-train-code`.
How do I find a station if I do not know its Chinese name?
Pass pinyin, short pinyin or the three-letter station code to `search-stations`: the search is fuzzy and covers at least 3382 stations.
How do I run the server in Docker?
Run `docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest`. To change the port, map a different external port, for example `-p 8080:8000`, and set `SERVER_HOST` and `SERVER_PORT` as environment variables.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server that searches China Railway 12306 tickets: schedules, train filters, transfers and intermediate stops
MCP server for Kaiten
mcp_server_for_kaiten
A simple Python MCP server for CRUD operations on Kaiten spaces, boards and cards
An MCP server for Kaiten: cards, comments, spaces and boards with control over response verbosity
Kaiten MCP (Python)
Kaiten MCP
A single-file FastMCP server for Kaiten: 22 tools for cards, comments, checklists and time tracking
Trello MCP server with 57 tools: cards, lists, checklists, attachments, comments, custom fields and workspaces, plus acceptance-criteria extraction
Travelpayouts MCP server
travelpayouts-mcp
An MCP server for Travelpayouts, the company behind Aviasales: cheap flight search, a price calendar and hotels
README in short
A Chinese-language page: a feature table, three ways to run (stdio, HTTP, Docker), the tool list with required parameters, environment variables and the project layout. It ends with a developer guide and a disclaimer.