12306-mcp: an MCP server for China Railway ticket search

What 12306-mcp actually does, and who it is aimed at

The project is a server that implements the Model Context Protocol and answers queries about China Railway tickets from the 12306 system. The README describes it as a 12306 ticket search server that provides a simple API interface so that a large model can search 12306 purchase information. That sentence sets the boundary: search, not purchase. There is no seat hold, no order submission, no payment path in the documented feature table.

The audience is narrow but real. If you run an MCP-capable client and you want it to answer questions like which trains run between two stations on a given date, this server is the adapter. Without it, a model has no structured way to reach 12306; with it, the model gets a tool it can call. The README's own framing is modest, and the Murmurs section states the project is for learning purposes only. Treat that as the author's stated intent rather than a disclaimer to skim past.

The feature table lists four completed capabilities: querying 12306 purchase information, filtering train information, stopover queries (过站查询), and transfer queries (中转查询). A fifth row says other interfaces are planned and invites feature requests. So the surface area today is query-shaped, and the transfer and stopover entries matter because direct trains are not always the answer between smaller stations.

How the server is put together

The repository is JavaScript, and the badges in the README include a TypeScript badge, which is consistent with a TypeScript codebase compiled for Node. The README links two internal documents: docs/principle.md, described as an explanation of how the service works, and docs/architecture.md with an architecture diagram rendered as docs/architecture.png. Those files are the place to look for the request path; the README itself does not restate them.

What is visible from the outside is the transport shape. The server can run over stdio, which is the default when you invoke the package with no arguments, or over HTTP when you pass a port. That is a two-mode design: stdio for a locally spawned child process managed by the MCP client, HTTP for a long-running process that clients reach over the network. The Docker examples follow the same split, with the HTTP variant mapping a host port to 8080 inside the container.

Beyond transport, the README does not document the internal data flow, the upstream 12306 endpoints used, or any caching layer. If you need to know whether the server caches station lists or re-queries on every call, the supplied material does not say. That is a gap worth closing by reading docs/principle.md before you rely on the server under load.

Installing and running it

There are two paths. From source, the README gives git clone followed by npm i in the cloned directory. For a quick run without cloning, the package is published and can be started with npx -y 12306-mcp for stdio, or npx -y 12306-mcp --port [端口号] for HTTP, where the bracketed value is the port number you choose.

Runtime requirements are stated plainly: Node.js 18 or newer for the server. There is a separate note that npm run debug uses MCP Inspector 2.0.0, which needs Node.js 22.19.0 or newer. If you are on Node 18 and the debug command fails, that version note is the first thing to check.

Client configuration is a standard MCP server block. The README's example registers a server named 12306-mcp with command npx and args ["-y", "12306-mcp"] inside an mcpServers object. Paste that into your client's config file and the client will spawn the server on demand. The Docker route is two commands: docker build . -t 12306-mcp to build the image, then docker run --rm -it 12306-mcp npx 12306-mcp for stdio, or docker run -p [your_port]:8080 -d 12306-mcp npx 12306-mcp --port 8080 for HTTP. Note the container command re-invokes npx inside the image rather than running a baked entrypoint, which means the container needs network access to the npm registry at start time.

Where it falls short

The most consequential limitation is scope. The README documents search, filtering, stopover and transfer queries. It does not document booking. If your goal is to have an assistant complete a purchase, this server is the wrong tool and no amount of MCP wiring will change that, because the capability is not in the feature table.

Second, the project depends on 12306 as an external system that the author does not control. The README says nothing about rate limits, retry behaviour, or what happens when 12306 changes a response shape. A ticket search server is only as reliable as the endpoint behind it, and there is no documented contract for that endpoint here. The absence of a stated data source in the README is itself a reason to read docs/principle.md before deployment.

Third, the maintenance signal is mixed. Releases exist and are recent: v0.3.8 in March 2026, v0.3.9 in June 2026, v0.3.10 in July 2026, with the last push at the end of July 2026. That is a steady cadence. But the README still carries an open row for other interfaces and a Murmurs line asking for patience, which reads as a side project rather than something with a support commitment. Plan for the possibility that a breaking 12306 change sits unfixed for a release cycle.

Finally, the licence is MIT, which is permissive and permits commercial use and modification provided the copyright notice and licence text are retained. That is a general description of MIT, not legal advice; read the LICENSE file in the repository and consult counsel if the use matters.

How it compares with writing your own 12306 client

The realistic alternative is not another MCP server. It is a small script or service that calls the 12306 query endpoints directly and returns JSON to whatever agent framework you already use. The difference in approach is where the protocol work lives. With 12306-mcp, the MCP handshake, tool schema, stdio or HTTP transport, and the query-to-tool mapping are already written, and you configure a client rather than build one. With a hand-rolled client, you own the transport, the tool definitions, and the response shaping, but you also control caching, retries, and exactly which fields reach the model.

That control matters in one specific case: if you need to combine 12306 data with other sources inside a single tool call, a custom function is simpler than composing several MCP tools. The reverse case also holds. If all you want is a chat client that can answer train questions, standing up your own server is work you do not need to do, and the npx invocation is a one-line config entry.

A second comparison point is the author's own related project. The README points to Joooook/12306-skill for a Skill-based integration. The README does not describe how the two differ in mechanism, so the only honest statement is that a parallel integration path exists and you should read that repository before choosing. Do not assume feature parity in either direction.

What to check before you commit to it

Start with docs/principle.md and docs/architecture.md in the repository. The README defers to them for the working principle and the architecture diagram, and those two files are where the upstream call pattern and any caching behaviour would be described. If they do not answer how the server behaves when 12306 returns an error or an empty result set, you have found an operational unknown.

Then confirm the runtime on the machine that will host the server. Node.js 18 is the floor for the server itself, and 22.19.0 is the floor for the MCP Inspector debug path. For the HTTP mode, decide whether the port you pass is reachable only from localhost or from your network, because the README's Docker example publishes the port on the host with -p [your_port]:8080.

Finally, decide what the server is allowed to see. It is a query tool against a public ticketing site, and the README does not discuss authentication, personal data, or logging. If your MCP client sends passenger details in a prompt, nothing in the supplied material tells you what the server does with them. Keep prompts to route, date, and train filters until you have read the source.

Editorial conclusion

Adopt 12306-mcp if you want an MCP client such as Claude Desktop or MCP Inspector to answer train-schedule questions against 12306 without writing a scraper, and you accept that the project is described as being for learning. Do not adopt it if you need ticket purchase, seat locking, payment, or any guarantee about upstream interface stability, because none of that is in scope. Before wiring it into anything you depend on, verify three things yourself: that Node.js 18 or newer is available on the host, that the 12306 endpoints the server calls still respond from your network, and whether the MIT licence and the project's learning-only framing are acceptable for your use.

Official sources

1. Issues
2. Joooook/12306-mcp on GitHub
3. License: MIT
4. README
5. Releases