MCP Server 12306

Skill by ara.so — MCP Skills collection.

MCP Server 12306 is a Model Context Protocol server that provides real-time access to China Railway 12306 data including train tickets, station information, transfers, prices, and schedules. Built with FastAPI for high-performance async operations.

What It Does

This MCP server exposes tools for:

Real-time ticket queries: Search available tickets with seat types, departure/arrival times
Station search: Fuzzy search for stations by Chinese name, pinyin, or abbreviation
Transfer planning: Find one-transfer routes between cities
Price queries: Get real-time ticket prices for trains
Route information: Query train stops and schedules
Time utilities: Get current time and relative dates for booking

Installation

For Claude Desktop (Stdio Mode - Recommended)

Add to your Claude Desktop configuration file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Using uvx (fastest):

json

{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

Using pipx:

json

{
  "mcpServers": {
    "12306": {
      "command": "pipx",
      "args": ["run", "--no-cache", "mcp-server-12306"]
    }
  }
}

From source (for development):

json

{
  "mcpServers": {
    "12306": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_12306.cli"],
      "cwd": "/path/to/mcp-server-12306"
    }
  }
}

For Remote/HTTP Mode (Streamable HTTP)

Local development:

bash

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync
uv run python scripts/start_server.py

Then configure your MCP client:

json

{
  "mcpServers": {
    "12306": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker deployment:

bash

docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

Available Tools

1. query_tickets

Search for available train tickets between stations.

Parameters:

```
from_station
```
(string, required): Departure station name (Chinese or pinyin)
```
to_station
```
(string, required): Arrival station name (Chinese or pinyin)
```
train_date
```
(string, required): Travel date in YYYY-MM-DD format
```
purpose_codes
```
(string, optional): "ADULT" (default) or "0X00" for student tickets

Example usage:

python

# Search tickets from Beijing to Shanghai on a specific date
result = await mcp_client.call_tool("query_tickets", {
    "from_station": "北京",
    "to_station": "上海",
    "train_date": "2025-06-15",
    "purpose_codes": "ADULT"
})

Response includes:

Train number, type (G/D/K/T/Z)
Departure/arrival times and duration
Seat availability and types
Station codes

2. query_ticket_price

Get real-time ticket prices for a specific train.

Parameters:

```
train_no
```
(string, required): Train number (e.g., "G101")
```
from_station_no
```
(string, required): Departure station code
```
to_station_no
```
(string, required): Arrival station code
```
seat_types
```
(string, required): Comma-separated seat type codes
```
train_date
```
(string, required): Travel date in YYYY-MM-DD format

Example usage:

python

# Get prices for train G101
result = await mcp_client.call_tool("query_ticket_price", {
    "train_no": "G101",
    "from_station_no": "BJP",
    "to_station_no": "SHH",
    "seat_types": "9,M,O",
    "train_date": "2025-06-15"
})

Response includes:

Price for each seat type
Seat type codes and names
Currency (CNY)

3. search_stations

Search for railway stations by name, pinyin, or abbreviation.

Parameters:

```
keyword
```
(string, required): Search term (Chinese, pinyin, or abbreviation)

Example usage:

python

# Search stations containing "beijing"
result = await mcp_client.call_tool("search_stations", {
    "keyword": "beijing"
})

# Also works with Chinese
result = await mcp_client.call_tool("search_stations", {
    "keyword": "北京"
})

Response includes:

Station name (Chinese)
Station code
Pinyin and abbreviation
Match score

4. get_station_info

Get detailed information about a specific station.

Parameters:

```
station_name
```
(string, required): Exact station name or code

Example usage:

python

result = await mcp_client.call_tool("get_station_info", {
    "station_name": "北京南"
})

5. query_transfer

Find one-transfer routes between cities (when no direct train available).

Parameters:

```
from_station
```
(string, required): Departure station
```
to_station
```
(string, required): Arrival station
```
train_date
```
(string, required): Travel date in YYYY-MM-DD format
```
purpose_codes
```
(string, optional): Ticket type

Example usage:

python

# Find transfer routes from Beijing to Guilin
result = await mcp_client.call_tool("query_transfer", {
    "from_station": "北京",
    "to_station": "桂林",
    "train_date": "2025-06-20",
    "purpose_codes": "ADULT"
})

Response includes:

First leg train details
Transfer station
Second leg train details
Total duration
Layover time at transfer station

6. get_train_route_stations

Query all stops and schedule for a specific train.

Parameters:

```
train_no
```
(string, required): Train number
```
from_station_telecode
```
(string, required): Origin station code
```
to_station_telecode
```
(string, required): Destination station code
```
depart_date
```
(string, required): Departure date in YYYY-MM-DD format

Example usage:

python

result = await mcp_client.call_tool("get_train_route_stations", {
    "train_no": "G101",
    "from_station_telecode": "BJP",
    "to_station_telecode": "SHH",
    "depart_date": "2025-06-15"
})

Response includes:

Station sequence
Arrival/departure times
Stop duration
Running distance

7. get_current_time

Get current time and calculate relative dates for booking.

Parameters:

```
timezone
```
(string, optional): Timezone (default: "Asia/Shanghai")

Example usage:

python

result = await mcp_client.call_tool("get_current_time", {
    "timezone": "Asia/Shanghai"
})

Response includes:

Current time
ISO format timestamp
Unix timestamp
Formatted date strings
Relative dates (today, tomorrow, next week)

Common Patterns

Complete ticket search workflow:

python

# 1. Get current time to determine valid booking dates
time_info = await client.call_tool("get_current_time", {})
travel_date = time_info["dates"]["tomorrow"]

# 2. Search for station codes if needed
stations = await client.call_tool("search_stations", {
    "keyword": "beijing"
})
from_code = stations[0]["code"]

stations = await client.call_tool("search_stations", {
    "keyword": "shanghai"
})
to_code = stations[0]["code"]

# 3. Query available tickets
tickets = await client.call_tool("query_tickets", {
    "from_station": "北京",
    "to_station": "上海",
    "train_date": travel_date,
    "purpose_codes": "ADULT"
})

# 4. Get price for specific train
if tickets["trains"]:
    train = tickets["trains"][0]
    prices = await client.call_tool("query_ticket_price", {
        "train_no": train["station_train_code"],
        "from_station_no": train["from_station_telecode"],
        "to_station_no": train["to_station_telecode"],
        "seat_types": train["seat_types"],
        "train_date": travel_date
    })

Finding transfer routes:

python

# When no direct trains available, query transfers
transfers = await client.call_tool("query_transfer", {
    "from_station": "拉萨",
    "to_station": "厦门",
    "train_date": "2025-07-01",
    "purpose_codes": "ADULT"
})

# Each result shows:
# - First train to transfer city
# - Layover duration
# - Second train to final destination
for route in transfers["transfer_routes"]:
    print(f"Transfer at: {route['transfer_station']}")
    print(f"Layover: {route['layover_minutes']} minutes")
    print(f"Total duration: {route['total_duration']}")

Checking train route details:

python

# Get complete route for a train
route = await client.call_tool("get_train_route_stations", {
    "train_no": "G7",
    "from_station_telecode": "BJP",
    "to_station_telecode": "SHH",
    "depart_date": "2025-06-15"
})

# Shows all stops with arrival/departure times
for stop in route["stations"]:
    print(f"{stop['station_name']}: {stop['arrive_time']} - {stop['start_time']}")

Configuration

Environment Variables

The server uses default 12306 public APIs and doesn't require API keys. However, you can configure:

Port (HTTP mode only): Set via
```
PORT
```
environment variable (default: 8000)
Timezone: Pass to
```
get_current_time
```
tool (default: "Asia/Shanghai")

Station Data

The server includes a pre-built station database. To update:

bash

cd scripts
uv run python update_station_data.py

This fetches the latest station list from 12306 and updates

src/mcp_12306/data/station_names.json

Project Structure

src/mcp_12306/
├── server.py           # FastAPI main entry point
├── services/
│   ├── ticket_service.py    # Ticket query logic
│   ├── station_service.py   # Station search logic
│   └── http_service.py      # 12306 API client
├── utils/
│   ├── config.py           # Configuration
│   └── logger.py           # Logging
├── data/
│   └── station_names.json  # Station database
scripts/
├── start_server.py         # HTTP mode launcher
└── update_station_data.py  # Station data updater

Troubleshooting

"Station not found" errors

The station database uses exact matching. Use

search_stations

first to find the correct station name:

python

# Search before querying
results = await client.call_tool("search_stations", {
    "keyword": "beijing"
})
# Use the exact name from results
station_name = results[0]["name"]

No tickets available

Check date format is YYYY-MM-DD
12306 typically allows booking 15-30 days in advance
Use
```
get_current_time
```
to get valid booking dates
Try different dates or use
```
query_transfer
```
for indirect routes

HTTP connection errors

Ensure the server is running (
```
uv run python scripts/start_server.py
```
)
Check port 8000 is not in use
For Docker, verify port mapping:
```
-p 8000:8000
```
In China, direct 12306 API access may require proper network access

Stdio mode not working in Claude Desktop

Restart Claude Desktop after configuration changes
Verify JSON syntax in config file
Check
```
uvx
```
or
```
pipx
```
is installed:
```
uvx --version
```
For source mode, ensure
```
cwd
```
points to correct directory

Rate limiting

The 12306 API may rate-limit requests. The server includes basic retry logic, but for production use:

Add delays between requests
Cache frequently accessed data (stations, routes)
Use transfer queries sparingly (they make multiple API calls)

Best Practices

Always get current time first: Use
```
get_current_time
```
to determine valid booking dates
Search stations before querying: Verify exact station names with
```
search_stations
```
Check direct routes first: Try
```
query_tickets
```
before
```
query_transfer
```
Cache station data: Station codes rarely change, cache
```
get_station_info
```
results
Handle no-results gracefully: Not all routes have direct or one-transfer options
Use appropriate date formats: Always use YYYY-MM-DD for dates

Legal Notice

This project is for educational and research purposes only. It queries publicly available 12306 APIs and does not store, modify, or distribute official data. Users must comply with Chinese laws and 12306 terms of service. The authors assume no liability for misuse.

mcp-server-12306

NPX Install

Tags

SKILL.md Content

MCP Server 12306

What It Does

Installation

For Claude Desktop (Stdio Mode - Recommended)

Using uvx (fastest):

Using pipx:

From source (for development):

For Remote/HTTP Mode (Streamable HTTP)

Local development:

Docker deployment:

Available Tools

1. query_tickets

2. query_ticket_price

3. search_stations

4. get_station_info

5. query_transfer

6. get_train_route_stations

7. get_current_time

Common Patterns

Complete ticket search workflow:

Finding transfer routes:

Checking train route details:

Configuration

Environment Variables

Station Data

Project Structure

Troubleshooting

"Station not found" errors

No tickets available

HTTP connection errors

Stdio mode not working in Claude Desktop

Rate limiting

Best Practices

Legal Notice