How to Query Train Tickets with Natural Language: Build Your MCP Assistant in 30 Minutes

How to Query Train Tickets with Natural Language: Build Your MCP Assistant in 30 Minutes

Do you often find it tedious to manually open 12306, pick dates, and scroll through train numbers every time you help family or friends book tickets during holidays? If you're already using MCP-compatible AI tools like Claude or Cursor, this tutorial is for you.

I'll walk you through building a 12306 MCP Server from scratch and integrating it into your daily AI workflow. Once set up, you can simply ask your AI, "Check high-speed train tickets from Beijing to Shanghai for National Day," and it will automatically call the API, fetch the data, and format the results for you. The whole process takes about 30 minutes, zero business logic coding required.

Prerequisites

Before diving in, make sure your machine meets these requirements:

• Node.js 18 or higher (recommend using nvm for easy version switching). Check with: node -v
• npm (comes pre-installed with Node.js)
• An MCP-compatible AI client, such as Claude Desktop, Cursor, or Windsurf
• Basic command-line familiarity

No prior knowledge of the MCP protocol is needed. Just follow along, and I'll explain the mechanics behind each step.

Step 1: Clone the Repo & Install Dependencies

Open your terminal and run:

git clone https://github.com/Joooook/12306-mcp.git
cd 12306-mcp
npm i

These commands pull the source code locally and install all dependencies via npm i. Think of it as giving your AI tool a "translator," and these npm packages are the translator's dictionary.

Step 2: Verify the Server is Running

There are two run modes. Let's start with the simplest: stdio mode.

npx -y 12306-mcp

This starts the service. Since stdio communicates with AI clients via standard input/output, the terminal won't show much visual feedback. If the cursor blinks without throwing errors, it's running fine.

For a clearer view, you can run it in HTTP mode:

npx -y 12306-mcp --port 8080

HTTP mode spins up a service on a specified port, making debugging and standalone testing much easier. I recommend using HTTP mode for your first run to confirm everything works, then switching back to stdio for AI client integration.

Node.js Version Note: If you plan to use npm run debug (MCP Inspector), you'll need Node.js 22.19.0+. For just running the server, 18+ is sufficient.

Step 3: Connect to Your AI Client

With the server running, it's time to tell your AI client where to find it. Using Claude Desktop as an example, you'll need to modify its MCP configuration file.

Edit MCP Config

Open Claude Desktop's MCP config file (usually found in Settings under MCP Servers) and add this JSON:

{
    "mcpServers": {
        "12306-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "12306-mcp"
            ]
        }
    }
}

This config tells Claude Desktop: when 12306 capabilities are needed, spawn the service via npx -y 12306-mcp and communicate over stdio.

Why use npx instead of a local path?
npx automatically resolves package paths, saving you from hardcoding absolute paths. This makes the config portable—you can share it with colleagues or use it on another machine without breaking it.

Save the config and restart Claude Desktop to apply changes. After restarting, you should see a status indicator showing the MCP Server is connected.

Step 4: Query Tickets with Natural Language

Now for the fun part.

Open a new chat in Claude Desktop and try a natural language prompt:

"Check high-speed train tickets (G-series) from Beijing South to Shanghai Hongqiao for tomorrow."

Claude will automatically detect the available 12306-mcp tool, call the service to query real-time ticket data, and return a neatly formatted response.

You can also try more advanced queries:

• Transfer routes: "If there are no direct tickets from Beijing to Kunming, recommend a transfer option."
• Station stops: "Which stations does train G101 stop at?"
• Filtered searches: "Find tickets from Shenzhen North to Guangzhou South for the day after tomorrow, only second-class seats with available seats."

The 12306-mcp project currently supports four core features: ticket info queries, train filtering, station stop queries, and transfer routing. It covers almost all daily ticket-checking needs.

Step 5: Docker Deployment (Optional)

If you prefer running this on a server or want to avoid cluttering your local Node.js environment, Docker is the cleanest approach.

## Build the image
docker build . -t 12306-mcp

## Run in stdio mode
docker run --rm -it 12306-mcp npx 12306-mcp

## Run in HTTP mode (port mapping)
docker run -p 8080:8080 -d 12306-mcp npx 12306-mcp --port 8080

Docker ensures environment isolation and simplifies deployment. Just adapt the MCP config to use the Docker runtime command instead; the underlying principle remains the same.

Troubleshooting & Common Pitfalls

1. Node.js version too low: If you hit weird errors, check node -v and ensure it's >= 18. Switch quickly with nvm: nvm install 22 && nvm use 22
2. Slow npm installs: Switch to a domestic mirror: npm config set registry https://registry.npmmirror.com
3. Claude Desktop won't connect: Double-check your MCP config JSON syntax (an extra comma will break it), and make sure you restarted the client.
4. No data returned: The 12306 API sometimes rate-limits. Try again later, or verify your network can access the official 12306 website.

Wrap-Up

Let's recap what we built today:

1. Cloned the repo & installed dependencies
2. Ran the MCP Server locally (stdio or HTTP mode)
3. Configured the MCP connection in your AI client
4. Used natural language to query train tickets via AI

By completing this workflow, you've gained more than just a handy ticket-checking tool. You've mastered how to integrate MCP services. The next time you encounter another MCP-compatible tool—whether for weather, database operations, or smart home control—you can plug it in using the exact same pattern.

Want to dive deeper? Check out the Principle Explanation and Architecture Diagram in the project's docs folder to understand how the MCP protocol communicates under the hood. Also, consider giving the repo a Star if you find it useful.

Drop a comment if you run into any issues. See you in the next post!