12306-mcp: Query China Train Tickets via MCP Server and LLMs

12306-mcp is a Model Context Protocol (MCP) server that retrieves real-time ticket data from China's 12306 railway system. It provides large language models with a structured API to access train schedules, seat availability, station lookups, and route planning. Because it operates over the Model Context Protocol, it eliminates the need for fragile browser automation or screen scraping, delivering clean, machine-readable data directly to the AI.

API Endpoints

1. get-tickets — Check Seat Availability

Parameters:

{
  "date": "2025-04-15",
  "from_station": "BJP",
  "to_station": "SHH"
}

Sample Response:

G103 北京南 (Beijing South) -> 上海虹桥 (Shanghai Hongqiao) 06:20 -> 11:58 Duration: 05:38
Business Class: 20 seats ¥1998
First Class: Available ¥969
Second Class: Available ¥576

G1 北京南 (Beijing South) -> 上海 (Shanghai) 07:00 -> 11:29 Duration: 04:29
Business Class: 8 seats ¥2331
First Class: 2 seats ¥1067
Second Class: Sold out ¥667
Preferred First Class: 2 seats ¥1467

G105 北京南 (Beijing South) -> 上海虹桥 (Shanghai Hongqiao) 07:17 -> 13:03 Duration: 05:46
Business Class: 7 seats ¥1873
First Class: Available ¥930
Second Class: Sold out ¥553

G107 北京南 (Beijing South) -> 上海虹桥 (Shanghai Hongqiao) 07:25 -> 13:12 Duration: 05:47
Business Class: 5 seats ¥2158
First Class: Sold out ¥1006

2. get-station-codes-by-city — Find Station Codes

Parameters:

{
  "city": "上海"
}

Sample Response:

[
  {"station_code":"LTU","station_name":"练塘"},
  {"station_code":"SHH","station_name":"上海"},
  {"station_code":"SNH","station_name":"上海南"},
  {"station_code":"AOH","station_name":"上海虹桥"},
  {"station_code":"SXH","station_name":"上海西"},
  ...
]

Installation and Startup

Clone and Install

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

Run the Server

You can use npx for an immediate start:

npx -y 12306-mcp

MCP Configuration

To integrate the server with your MCP client (such as Claude Desktop or a Gemini environment), add the following to your configuration file (e.g., ~/.gemini/settings.json):

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

Architecture Overview

The system is organized into a four-layer stack. At the top level, the user or LLM interacts with high-level tools like get-tickets and get-station-codes-by-city. Beneath this, the core tool layer handles the specific query logic and formats the raw data into readable responses. The MCP server acts as the bridge between these internal tools and the external environment, translating incoming requests for the 12306 API. This design ensures that data remains clean and structured, removing the need for HTML parsing or CAPTCHA handling. By abstracting these complexities, the server allows the LLM to focus on answering complex user prompts, such as: "Find me afternoon trains from Beijing to Shanghai with available first-class seats."