12306-mcp: Train Ticket Inquiry Server based on MCP Protocol

12306-mcp is a Model Context Protocol (MCP) based train ticket query server designed for querying China Railway 12306 ticket information. It provides an easy-to-use API interface for users or developers to quickly access real-time train ticket information through the program. The project, hosted on GitHub and created by developer Joooook, aims to provide efficient ticket query support for AI assistants or automation tools. The server supports querying remaining tickets, train information, stops, and transit options, making it suitable for scenarios that require quick access to ticket data. The project is for learning purposes only, emphasizes not storing or tampering with official data, and focuses on the simplicity and practicality of the interface.

Function List

• Check 12306 train ticket information, including remaining tickets, number of trains, seat types and schedules.
• Filter train information, support filtering by time, fare or train type.
• Search for train stop information, get passing cities and stopping times.
• Support transit inquiry and provide one-stop transfer scheme suggestions.
• Provides a simple API interface for easy integration into AI assistants or automation programs.
• Supports fuzzy search for station information across the country, making it easy to quickly locate stations.

Using Help

Installation process

To use the 12306-mcp server, follow the steps below to deploy it locally or on a server:

1. Cloning Project Code
   Use the Git command to download the project source code:

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

2. Installation of dependencies
   Go to the project directory and install the Node.js dependencies:

   cd 12306-mcp
   npm i
   

3. Build the project
   Run the build command to generate the executable:

   npm run build
   

4. Start the server
   Execute the following command to start the server:

   node ./build/index.js
   

5. Configuring the MCP Server
   If you need to integrate 12306-mcp into a system that supports the MCP protocol, you need to add the following to the configuration file:

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

   Configuration file paths are usually located in clients or platforms supported by the MCP protocol, please refer to the documentation of the target system for specific paths.

Usage

After deployment, 12306-mcp provides a set of API interfaces that developers or AI assistants can call via HTTP requests. The following is the operation flow of the main functions:

1. Searching for train ticket information

Users can send requests through the API to query train ticket information for a specified date, origin and destination. For example, query train tickets from Beijing to Shanghai:

• API Request Example::

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22
  

• Return data: JSON format, including the number of trips, departure time, arrival time, fare, and number of remaining tickets.
• procedure::
  1. Determine the origin, destination and date.
  2. Send a GET request using an HTTP client (such as Postman) or code.
  3. Parses the returned JSON data to get the available trips and fares.
• take note of: Departure and destination need to use 12306 official station name or code, support fuzzy search.

2. Filtering train information

Users can filter trains according to their needs, such as viewing only high-speed trains or night trains:

• API Request Example::

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22&type=highspeed
  

• procedure::
  1. Add filter parameters to the request, such as type=highspeed(High Speed Rail) or time=night(at night).
  2. The server returns a list of eligible trips.
  3. Users can further sort by fare or duration.

3. Search for stops

Queries the stops and stopping times of a particular train:

• API Request Example::

  GET /train/stops?trainNo=G123
  

• Return data: JSON format with the name of the passing station, arrival time and stopover time.
• procedure::
  1. Get the target train number (e.g. G123).
  2. Send a request to get a list of stops.
  3. You can combine it with the map tool to generate travel tips and plan your itinerary for the cities you are passing through.

4. Transit inquiries

For routes without direct trains, the server provides transit options:

• API Request Example::

  GET /transfer?from=Xian&to=Zhengzhou&date=2025-07-22
  

• Return data: Recommended stopovers, transfer times and total trip length.
• procedure::
  1. Enter the origin, destination and date.
  2. Server return transit program, such as the specific number and time of the transfer in Wuhan.
  3. Users can choose the optimal plan based on total duration or fare.

5. Fuzzy search stations

Supports inputting partial station names to find complete information:

• API Request Example::

  GET /stations?name=Hang
  

• Return data: Includes detailed information about the station "Hangzhou" and "Hangzhou East".
• procedure::
  1. Enter part of the station name in pinyin or Chinese characters.
  2. The server returns a list of matching stations.
  3. Select the correct station code from the list to use for ticket lookup.

caveat

• Data sources: All ticket data comes from the official 12306 interface, the server only aggregates and forwards, does not store data.
• utilization risk: Frequent requests may trigger the anti-climbing mechanism of 12306, it is recommended to set the request frequency reasonably.
• Development Support: The project welcomes developers to contribute new features, and feature requests can be submitted via GitHub.

application scenario

1. AI Assistant Integration
   12306-mcp can be embedded with AI assistants (e.g., intelligent chatbots), so that users can input "train tickets from Shanghai to Hangzhou tomorrow" by voice or text, and the assistant will call the API to return real-time ticket information and quickly provide the number of train trips and fares.
2. Travel planning tools
   Developers can integrate 12306-mcp into their travel planning applications, combining stop information to generate travel guides for the cities they pass through. For example, if you are looking for a train from Beijing to Guangzhou, you can recommend attractions in Wuhan.
3. Automated Ticket Inquiry
   Enterprises can use 12306-mcp to develop an automated ticket monitoring tool to track the remaining tickets of a certain line in real time, which is suitable for travel management or ticket agency scenarios.
4. Education and Research
   Students or developers can use 12306-mcp to learn the implementation of the MCP protocol and study how to aggregate third-party data through APIs, suitable for computer courses or open source project practice.

QA

1. Is there a fee for 12306-mcp?
   The project is completely open source, free to use, hosted on GitHub, and requires only self-deployment of the server.
2. Does it support real-time ticket updates?
   Yes, the server gets real-time data through the official 12306 interface to ensure accurate ticket information.
3. How to avoid triggering 12306's anti-crawl mechanism?
   It is recommended to set reasonable request intervals (e.g., no more than 5 times per minute) to avoid high-frequency requests within a short period of time.
4. Can I use it directly on my phone?
   It currently needs to be deployed on a computer or server, and cell phones can be accessed via an API client, or wait for a possible future mobile adaptation.
5. What programming languages are supported to call the API?
   The API uses the standard HTTP protocol and can be called by any language that supports HTTP requests (e.g. Python, JavaScript).