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

12306-mcp

by Joooook · Joooook/12306-mcp

Query China's 12306 railway tickets via AI — search trains, check availability, and plan routes with natural language.

12306-mcp is an MCP server that connects AI assistants to China's official 12306 railway system. It supports ticket availability queries, train filtering, transit stop lookups, and multi-leg transfer planning. Runs via npx, Docker, or HTTP mode for flexible deployment.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

12306-mcp-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": {
    "12306-mcp-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/Joooook/12306-mcp"
      ]
    }
  }
}

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

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

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

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

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

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

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

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

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

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

Add to context_servers. Zed hot-reloads on save.

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

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

Use Cases

Real-world ways to use 12306-mcp

How to find the cheapest train between two cities with 12306-mcp

👤 Travelers planning trips within China ⏱ ~5 min beginner

When to use: You need to compare train options between two Chinese cities and find the best deal.

Prerequisites
  • 12306-mcp server running — npx -y 12306-mcp
Flow
  1. Search for available trains
    Search for trains from Beijing to Shanghai tomorrow. Show me all available options with prices and seat types.✓ Copied
    → A table of trains with departure times, durations, seat classes, and prices
  2. Filter by preference
    Which of these has second-class seats available and arrives before 6pm?✓ Copied
    → Filtered list matching the criteria

Outcome: A clear comparison of train options to make a booking decision.

Pitfalls
  • Station names must match 12306's database exactly — Use the station search tool first to confirm the correct station name

Plan a multi-leg train journey with transfers using 12306-mcp

👤 Travelers heading to cities without direct trains ⏱ ~10 min beginner

When to use: No direct train exists between your origin and destination.

Prerequisites
  • 12306-mcp server running — npx -y 12306-mcp
Flow
  1. Query transfer options
    I need to get from Chengdu to Lhasa by train. Find me transfer routes with the shortest total travel time.✓ Copied
    → One or more transfer itineraries with intermediate stations and connection times
  2. Check availability on each leg
    Check ticket availability for each leg of the recommended route on March 15.✓ Copied
    → Seat availability for both legs of the journey

Outcome: A complete multi-leg itinerary with confirmed availability.

Pitfalls
  • Tight transfer windows may cause missed connections — Ask Claude to filter for transfers with at least 2 hours between trains

Combinations

Pair with other MCPs for X10 leverage

12306-mcp-2 + fetch

Combine train search with web fetch to check weather at your destination before booking

Find me a train from Shanghai to Hangzhou this Saturday, and check the weekend weather forecast for Hangzhou.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
query_tickets from: str, to: str, date: str Search for available train tickets between two stations 1 API call
search_stations keyword: str Look up station names and codes by keyword 1 API call
query_transfer from: str, to: str, date: str Find transfer routes when no direct train exists 1 API call
get_train_route_stations train_no: str Get all stops along a specific train's route 1 API call

Cost & Limits

What this costs to run

API quota
Depends on 12306 public API rate limits — typically sufficient for personal use
Tokens per call
200–800 tokens per query
Monetary
Free — queries the public 12306 API
Tip
Batch station lookups before running ticket queries to avoid redundant calls.

Security

Permissions, secrets, blast radius

Credential storage: No credentials required — uses public 12306 API endpoints
Data egress: All calls go to 12306.cn official API endpoints

Troubleshooting

Common errors and fixes

Station name not found

Use the station search tool to find the exact name. Chinese station names must match the 12306 database — try both simplified Chinese and pinyin.

Verify: Search for the station by keyword first
No trains found for the given date

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

Verify: Try a date within the next 15 days
Connection timeout

The 12306 API can be slow during peak booking times (e.g., Spring Festival). Retry after a few minutes.

Verify: Test with a simple station search to confirm connectivity

Alternatives

12306-mcp vs others

AlternativeWhen to use it insteadTradeoff
mcp-server-12306You want a Python-based alternative with FastAPI backend and additional price query toolsMore features (price queries, HTTP streaming) but requires Python/uv setup

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills