MCP Server 12306

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):

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

Using pipx:

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

From source (for development):

{
  "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:

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:

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

Docker deployment:

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:

# 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:

# 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:

# 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:

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:

# 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:

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:

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:

# 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:

# 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:

# 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:

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:

# 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

1. Always get current time first: Use get_current_time to determine valid booking dates
2. Search stations before querying: Verify exact station names with search_stations
3. Check direct routes first: Try query_tickets before query_transfer
4. Cache station data: Station codes rarely change, cache get_station_info results
5. Handle no-results gracefully: Not all routes have direct or one-transfer options
6. 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.