Recently I found a super practical project on GitHub - 12306-mcp, which is a 12306 ticket search server based on Model Context Protocol (MCP).

The 12306-mcp project allows the big model to use this interface to search for 12306 ticket purchase information, so the ticket purchase experience will be improved immediately!

12306-mcp features

Query 12306 ticket purchase information : The core function of the project is to realize the query of 12306 ticket information. By interacting with the 12306 official system, real-time ticket information can be obtained, including: train number, departure time, arrival time, seat type, fare and other detailed information.

Filter train information : Our users can filter the query results according to their travel plans and preferences, such as departure place, destination, date, train type and other conditions.

Passing station query : The passing station query function can help our users query the information of trains passing through specific stations. This function is very practical for friends who need to transfer midway or have special attention to a certain station.

Transfer query : The transfer query function is for those of us who have transfer needs. It can intelligently recommend transfer plans based on the user's departure and destination and the timetable of each train to help passengers plan a reasonable transfer itinerary.

Project technical architecture and principle analysis

Technical Architecture

Front-end and back-end separation architecture : The 12306-mcp project adopts a front-end and back-end separation architecture design. The front-end is mainly responsible for interacting with users, providing an intuitive operation interface and displaying query results;

The backend is responsible for handling business logic, data processing, and data connection with the 12306 official system. This makes it very simple and easy for us developers to modularize and maintain the project, while also improving the scalability of the system.

12306-MCP Service Principle

When the service is started, getStations() The function obtains national station information from the 12306 API and constructs four core indexes:

Specific process:

1. Visit the 12306 homepage (https://www.12306.cn/index/);
2. Extract station name JS file path from HTML;
3. Download and parse the JS file to obtain the original station data;
4. Supplement missing station information (MISSING_STATIONS);
5. Four core data structure mapping tables are obtained based on station data;

// 1. Station id -> station information STATIONS: Record<string, StationData> // "AAA": {// "station_id": "@aaa",// "station_name": "Beijing North",// "station_code": "AAA",// "station_pinyin": "beijingbei",// "station_short": "aaa",// "station_index": "0",// "code": "1234",// "city": "Beijing",// "r1": "",// "r2": ""// }// 2. City name -> station id and station name (a city may have multiple stations) CITY_STATIONS: Record<string, { station_code: string; station_name: string }> // "Beijing": [{"station_code": "AAA","station_name": "Beijing North"},{"station_code": "BBB","station_name": "Jingdong"},...]// 3. Station name (same as city name, only one) -> station id and station name CITY_CODES: Record<string, { station_code: string; station_name: string }> // "Beijing":{"station_code":"CCC","station_name":"Beijing"}// 4. Station name -> station id and station name NAME_STATIONS: Record<string, { station_code: string; station_name: string }> // "Beijing North":{"station_code":"AAA","station_name":"Beijing North"}

Data flow and tool relationship

Ticket inquiry process:

User query "High-speed rail from Beijing to Shanghai the day after tomorrow" - Big model call process: ↓1. get-current-date() → "2024-01-15" (Get the current date)2. The big model understands the date the day after tomorrow → "2024-01-17"3. get-station-code-of-citys("Beijing|Shanghai") → {"Beijing": {"station_code": "BJP","station_name": "Beijing"}, "Shanghai": {"station_code": "SHH","station_name": "Shanghai"}} ↓4. get-tickets(date: "2024-01-17", fromStation: "BJP", toStation: "SHH", trainFilterFlags: "G") ↓5. Internal data processing (parameter verification, Cookie acquisition, API call, formatted output text) ↓6. Return formatted high-speed rail train information (train number, time, price, remaining tickets, etc.)

 Transit inquiry process:

User query "Shenzhen to Lhasa, transfer via Xi'an" ↓1. Get the station IDs of the three cities 2. get-interline-tickets(from: "SZQ", to: "LSO", transfer: "XAY") ↓3. Internal data processing (parameter validation, Cookie acquisition, API call, formatted output text) ↓4. Return the transfer plan (first leg + second leg)

 Stop station query process:

User query "Which stations does the G1 train stop at" ↓1. get-train-route-stations(trainNo: "G1", from: "BJP", to: "SHH") ↓2. Data processing: parseRouteStationsData() → parseRouteStationsInfo() ↓3. Return the list of stopover stations (station name, arrival time, departure time, stay time)

Basic tool

• get-current-date : Get the current date in Shanghai time zone

• Returns the time and date string ("yyyy-MM-dd") of the current Shanghai time zone
• Provide accurate query date benchmarks for other tools

• get-stations-code-in-city: Query all stations in the city (using CITY_STATIONS）

• Input: Chinese city name
• Search for:CITY_STATIONS[city] Get a list of all stations in the city
• Returns: Contains station_code and station_name Array

• get-station-code-of-cities: Get the station ID representing the city (using CITY_CODES）

• Input: City name (supports multiple cities separated by "|")
• Search for:CITY_CODES[city] Get the main station with the same name as the city
• Return: the representative station information corresponding to each city

• get-station-code-by-names: Station name to station id (use NAME_STATIONS）

• Input: Specific station name (supports multiple stations separated by "|")
• Search for:NAME_STATIONS[stationName] Exactly match station name
• Return: station id and station name

• get-station-by-telecode: Check station information by station ID (use STATIONS）

• Input: station id
• Search for:STATIONS[telecode] Get complete station information
• Return: contains detailed information such as pinyin and city

Core tool (input can be obtained through the basic tool)

get-tickets : Query 12306 remaining ticket information

• Input: departure date, departure station ID, arrival station ID, train type filter
• Parameter processing: check that the date is not earlier than the current date, verify the existence of the station ID, and construct the request input parameter
• Cookie processing: first obtain 12306 Cookie for identity authentication
• API call: Access /otn/leftTicket/query interface
• Data processing, train type screening
• Returns formatted data

• get-interline-tickets: Transfer query, support designated transfer stations

• Input: departure station id, arrival station id, transfer station id, whether to display no seats, train type filter
• Parameter processing: check that the date is not earlier than the current date, verify the existence of the station ID, and construct the request input parameter
• Cookie processing: first obtain 12306 Cookie for identity authentication
• API call: Access /lcquery/queryU interface
• Data processing, train type screening
• Returns formatted data

• get-train-route-stations: Train stop query

• Input: train number (can be obtained by calling get-tickets), departure station id, arrival station id, departure date
• Parameter processing: check that the date is not earlier than the current date, verify the existence of the station ID, and construct the request input parameter
• Cookie processing: first obtain 12306 Cookie for identity authentication
• API call: Access /otn/czxx/queryByTrainNo interface
• Returns formatted data

12306-mcp installation configuration

CLI

npm run buildnode ./build/index.js

MCP server configuration

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

Effect display: