12306 MCP in Action: Query Train Tickets and Plan Routes with Natural Language AI

When 12306 Meets AI Agents

Buying train tickets, checking availability, planning transfer routes — these tasks seem simple but are often frustrating. Now you can hand them all off to an AI. A GitHub project called 12306-MCP has been drawing attention recently (already at 1K stars and actively maintained). It connects 12306's real-time query capabilities to various AI agents via the MCP (Model Context Protocol).

About MCP: MCP is a standardized protocol proposed and open-sourced by Anthropic in late 2024. It addresses the "last-mile" connectivity problem between large language models and external tools or data sources. Before MCP, every AI application that wanted to integrate an external service had to write a custom adapter — costly and hard to reuse. MCP's core idea is to define a unified "tool calling" specification: developers wrap external capabilities into MCP-compliant Servers, and any MCP-compatible AI client (Claude, Cursor, Cline, etc.) can automatically discover and invoke these tools without additional adaptation. This is analogous to what the USB standard did for hardware ecosystems — a standardized interface that enables rapid ecosystem growth. The MCP ecosystem now covers hundreds of tool Servers spanning database queries, web browsing, code execution, file management, and more. 12306-MCP is a prime example of this ecosystem applied to high-frequency everyday scenarios in China.

In short, once you configure this MCP in your preferred AI Agent (such as Trae/Hermes Agent, Codex, Cline, etc.), you can use natural language to check ticket availability, look up train stops, plan transfer routes, and even get optimal itinerary recommendations. The only limitation: it doesn't support booking tickets. Beyond that, it covers virtually every query scenario on 12306.

Core Features of 12306-MCP

Based on the project's public tool list, 12306-MCP includes 9 tool categories covering the full query workflow:

• Query current date: Resolves how the AI interprets relative time expressions like "today" or "tomorrow"
• Query all train stations and city codes: A prerequisite for ticket availability queries
• Ticket availability query: Check real-time availability by date, origin, and destination
• Transfer availability query: Automatically combines transfer options when no direct train is available
• Train stop query: View the complete stop schedule for a specific train

In terms of train types, high-speed rail, EMU trains, direct express, express, fast trains, as well as Fuxing and smart EMU trains are all supported — essentially mirroring the coverage of the official 12306 website.

Installation and Setup: Extremely Low Barrier

One of 12306-MCP's biggest strengths is how easy it is to install — no need to understand the code or manually edit complex JSON configuration files.

How to do it: Open the 12306-MCP project page on GitHub, then send the project URL or the MCP configuration example directly to your AI agent and let it handle the installation automatically. Both Trae's Hermes Agent and Codex can recognize and complete the MCP registration.

Once installed, all supported tools become available in your current agent environment, consistent with what's documented in the project. Users who want to customize or extend the functionality can also clone the repository locally.

Real-World Test: How Accurate Is the Data?

A tool's value ultimately comes down to data accuracy. The test used a real scenario: querying train tickets from Beijing to Hong Kong West Kowloon on a specific date.

After the agent automatically invoked 12306-MCP, it returned real-time results. One key usage tip: you must specify the exact date, origin, and destination — let the AI handle everything else.

The query results showed:

• G381: Beijing West → Hong Kong West Kowloon, departs 10:00, arrives 18:12, 8h 12min travel time — no seats available in business, first, or second class
• G897: Beijing West → Hong Kong West Kowloon, departs 9:01, arrives 19:19, 10h 18min travel time — 3 special-class seats, 1 second-class seat, 9 sleeper seats available

Why the data stays in sync: 12306-MCP does not store static ticket data. Instead, it fetches results in real time by calling 12306's official HTTP API. When the MCP Server receives a tool call request from an AI Agent, it immediately sends a request to 12306's backend, structures the raw response, and returns it to the Agent — with no local caching at any point. This is why it's "cleaner" than some third-party tools: read-only, no account login, no payment flow involved.

Cross-checking the results against the official 12306 website, the train numbers, departure/arrival times, and seat availability all matched exactly — confirming that 12306-MCP's data is in real-time sync with the official site, with no caching lag or data errors.

Advanced Use: AI Automatically Plans the Optimal Transfer Route

Basic ticket lookup is just the starting point. Where AI truly shines is multi-option comparative planning. The test posed a more complex request: "Help me plan the cheapest route and trains from Beijing to Xinjiang."

This demonstrates the AI Agent's autonomous planning capability: upon receiving this instruction, the Agent automatically enters a "ReAct" loop — first reasoning about what information is needed (city codes, direct trains, transfer combinations), then calling the relevant tools one by one, observing the results, and continuing to reason until it completes a full multi-option cost comparison. The entire process requires no step-by-step user guidance, making it significantly more efficient than manually switching between queries on the 12306 website.

Based on ticket availability and transfer data, the agent produced a full comparison (with Ürümqi as the destination):

• Cheapest option: Beijing West → Lanzhou (standing ticket) + Lanzhou → Ürümqi (standing ticket), total ~¥390.5, total journey ~34h 56min
• Middle-ground option: Beijing West → Lanzhou West (second class, ¥793.5) + Lanzhou West → Ürümqi (hard seat, ¥206, only 1 left), total ~¥999, total time ~24h — about 10 hours faster than the cheapest option
• Direct options: Dong619 and Z19 run direct from Beijing West to Ürümqi, starting from ¥412 and ¥352 respectively, but both were sold out at the time of query

The AI didn't just list prices — it clearly presented the trade-off between time cost and monetary cost. The cheapest option costs nearly half as much as the middle-ground option, but requires 10 extra hours of travel. This kind of "save money vs. save time" trade-off analysis is exactly what traditional ticketing tools struggle to provide.

The Value and Limitations of 12306-MCP

For frequent travelers who need to plan transfers, 12306-MCP can significantly cut down the time spent comparing options and running queries. Especially for long-distance, cross-regional trips, the AI's automatic transfer combination capability is noticeably better than manual searching.

That said, its limitations are worth understanding:

1. No ticket booking support — once you've decided on a route, you still need to go to 12306 manually to purchase
2. Requires an agent environment — you need an AI Agent that supports the MCP protocol
3. Query parameters must be explicit — date, origin, and destination are all required

Overall, as an open-source, free, easy-to-install query tool with real-time data sync, 12306-MCP is an excellent reference for how AI agents can be put to practical use in everyday life. It turns "check tickets + plan routes" — a high-frequency, genuine need — into something you can accomplish with a single natural language prompt. If you're exploring the practical value of the MCP ecosystem, this is a project well worth trying out.

Key Takeaways