/ Directory / Playground / mcp-server-12306
← All servers ↗ GitHub
● Community drfccv ⚡ Instant

mcp-server-12306

by drfccv · drfccv/mcp-server-12306

High-performance Python MCP server for 12306 — real-time tickets, prices, station search, train routes, and transfer planning.

mcp-server-12306 is a FastAPI-based MCP server providing real-time data from China's 12306 railway system. It offers 7 tools for ticket queries, price lookups, station search (Chinese/pinyin/abbreviation), train route stops, transfer planning, and time utilities. Supports both stdio (Claude Desktop) and Streamable HTTP modes, with Docker deployment and sub-second response times.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

mcp-server-12306-2.replay ▶ ready
0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-server-12306-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drfccv/mcp-server-12306"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-server-12306-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drfccv/mcp-server-12306"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-server-12306-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drfccv/mcp-server-12306"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-server-12306-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drfccv/mcp-server-12306"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-server-12306-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drfccv/mcp-server-12306"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-server-12306-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drfccv/mcp-server-12306"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcp-server-12306-2 -- TODO 'See README: https://github.com/drfccv/mcp-server-12306'

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use mcp-server-12306

How to compare train ticket prices for a journey with mcp-server-12306

👤 Budget-conscious travelers in China ⏱ ~5 min beginner

When to use: You want to find the cheapest option for your train journey.

Prerequisites
  • mcp-server-12306 running — uvx mcp-server-12306 or Docker: docker run -p 8000:8000 drfccv/mcp-server-12306:latest
Flow
  1. Search tickets with prices
    Query tickets from Beijing to Guangzhou for tomorrow. Show all available trains with prices for each seat class.✓ Copied
    → Table of trains with departure times, durations, and prices per seat class
  2. Get detailed pricing
    Show me the detailed pricing for train G79, including all seat types.✓ Copied
    → Complete fare breakdown for the specific train

Outcome: Clear price comparison to choose the best value train.

Pitfalls
  • Prices may vary by date and availability — Check availability alongside prices — cheap seats sell out first

Plan a multi-city train trip across China

👤 Tourists planning a scenic route through multiple Chinese cities ⏱ ~15 min beginner

When to use: You want to visit several cities and need to plan the train connections.

Prerequisites
  • mcp-server-12306 running — uvx mcp-server-12306
Flow
  1. Search stations
    Search for the main train stations in Shanghai, Hangzhou, and Suzhou. Show me the station codes.✓ Copied
    → Station names and codes for each city
  2. Plan the route
    Find the fastest train connections for: Shanghai → Hangzhou → Suzhou → back to Shanghai, spending one day in each city. Show departure times and durations.✓ Copied
    → Complete itinerary with train numbers and times

Outcome: A multi-city itinerary with all train connections planned.

Pitfalls
  • Small cities may only have one station — Use the station search to confirm available stations before planning

Combinations

Pair with other MCPs for X10 leverage

mcp-server-12306-2 + fetch

Check weather at your destination alongside train schedules

Find trains from Beijing to Chengdu this weekend and check the weather forecast for Chengdu.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
query_tickets from: str, to: str, date: str Search for available train tickets 1 API call
query_ticket_price train_no: str, from: str, to: str, date: str Get detailed pricing for a specific train 1 API call
search_stations keyword: str Search stations by name, pinyin, or abbreviation 1 API call
get_station_info station_code: str Get detailed station metadata 1 API call
query_transfer from: str, to: str, date: str Find optimal transfer routes 1 API call
get_train_route_stations train_no: str Get all stops along a train route 1 API call
get_current_time none Get current time for relative date calculations 0

Cost & Limits

What this costs to run

API quota
Subject to 12306 public API rate limits
Tokens per call
200–800 tokens per query
Monetary
Free — uses public 12306 API
Tip
Use station search to confirm names before querying tickets to avoid wasted calls.

Security

Permissions, secrets, blast radius

Credential storage: No credentials required
Data egress: All calls to 12306.cn official API

Troubleshooting

Common errors and fixes

No tickets found

12306 sells tickets 15 days in advance. Verify your date is within the booking window.

Verify: Try today's date to confirm connectivity
Station not recognized

Use search_stations first with pinyin or Chinese to find the exact station name.

Verify: search_stations with a broader keyword
Timeout during peak hours

12306 API is slow during peak ticket sales (holidays, Spring Festival). Retry after a few minutes.

Verify: Test with a simple station search

Alternatives

mcp-server-12306 vs others

AlternativeWhen to use it insteadTradeoff
12306-mcpYou prefer a JavaScript/npx-based server with simpler setupSimpler install but fewer features (no price queries or HTTP streaming)

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills