M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
1

12306 MCP Server

Community
MCP server for real-time 12306 train ticket queries
How to install ↓ Compare GitHub source repository ↗
Category
Other #30 of 230
Stars
★ 416 Very popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Python 3.10+ · Docker
Credentials
No credential needed
License
MIT
Last commit
Tools
7
66FMRS · C

This is an MIT-licensed third-party open-source MCP server that turns 12306's public query capabilities (availability, prices, stations, stopovers, transfers, time) into 7 MCP tools. It supports both Stdio and Streamable HTTP transports, offers a Docker image, and ships operational endpoints such as /health and /schema/tools, with a clean project layout and fairly complete documentation. It is not an official 12306 product and offers no booking operations, and the author states it is for learning and research with commercial use prohibited, making it a good fit for personal trip lookups and MCP development practice but unsuitable as a commercial system with SLA requirements.

Strongest · Documentation 15/20 Weakest · Reliability 11/20

Reliability
11/20
Security and permissions
13/20
Maintenance
13/20
Documentation
15/20
Setup experience
14/20
Why each score
Reliability 11/20
Evidence is limited to the README and server.json, both non-executable; no CI workflows and no committed tests are present, and the static rubric caps reliability at 12 without verifiable execution evidence. Positive signals: the manifest declares a single PyPI package with stdio transport and a version matching the README, the seven declared tools map cleanly to the README tool table, and the README describes a transport-agnostic core (server.py) shared by stdio and HTTP with a single schema source (ticket_service.MCP_TOOLS). Deductions: there are no tests, CI, error-code taxonomy, or failure-scenario coverage; dependence on live unofficial 12306 endpoints is unmitigated and unverified; runtime claims (loaded station count, active sessions) cannot be confirmed from files; and tool argument boundaries and return shapes are unproven. Score 11.
Security and permissions 13/20
No red-line behavior found: no malware, credential theft, covert exfiltration, irreversible delete/pay/deploy defaults, or fabricated identity. All tools are read-only queries (tickets, price, stations, transfer, route stops, train number, time), so privilege exposure is intrinsically low and no confirmation flows are needed. Risks and deductions: all traffic targets external 12306 endpoints, i.e. unofficial third-party data scraping that may trigger throttling, IP bans, or account restriction, which the README itself warns about; there is no authn/authz, rate limiting, caching, or audit logging documented; in HTTP mode the default SERVER_HOST=0.0.0.0 exposes /mcp, /health and /schema/tools with no authentication, which is an open invocation surface if deployed publicly; input-validation, SSRF and injection surfaces are not addressed; and there is no data-flow or privacy disclosure beyond a vague 'no storage/no tampering' statement. Given the low-sensitivity read-only scope but incomplete scoping and confirmation controls, score 13.
Maintenance 13/20
An MIT license is present, server.json declares version 0.5.0.post20260822, and the README shows PyPI/Docker/GitHub badges plus release commands (python -m build, twine upload), indicating a release pipeline. The repo is not archived, shows 386 stars and one open issue, and uses uv.lock, pydantic-settings, strict mypy, black and isort, indicating some engineering discipline. Deductions: commit cadence, issue response latency, dependency update cadence, maintainer identity, security-response channel, and contributor governance are unverifiable from static material; there is no SECURITY.md, no CHANGELOG and no CI record; the version string embeds a future-style date (post20260822) that looks odd but cannot be confirmed as wrong; and no security disclosure path is stated. Score 13.
Documentation 15/20
Documentation is fairly layered: the README includes a capability table, three deployment modes (stdio, Streamable HTTP, Docker), a table of seven tools with required parameters, an environment-variable table (SERVER_HOST/SERVER_PORT/DEBUG/LOG_LEVEL), a project-structure tree, a development guide, and a disclaimer, plus six per-tool documents under docs/ said to cover parameters, return examples and usage. Deductions: no tool return-shape examples, no error-code or troubleshooting section, no rate/quota/cost disclosure; authentication and data-flow disclosures are absent; the docs/ contents are not supplied as evidence so their accuracy cannot be verified; and the 0.0.0.0 default ships without a secure-deployment warning. Positioned as 'usable with hidden assumptions and troubleshooting gaps', score 15.
Setup experience 14/20
Install paths are clear and multiple: one-line uvx mcp-server-12306, pip/pipx alternatives, one-line docker run -p 8000:8000, plus source install via uv sync and scripts/start_server.py. The README provides Claude Desktop-style stdio config, a Streamable HTTP url config, and Docker examples with custom ports and env vars, and prerequisites are explicit (Python >=3.10,<3.14, uv recommended, reachable 12306). Deductions: installation success is not verified under static review; packaging claims versus implementation cannot be confirmed; HTTP mode requires the user to manage ports, deployment and security boundaries; Docker tag/version sync with PyPI is unknown; and there is no troubleshooting guidance for Windows or network-restricted/proxy failures. Positioned as 'works but manual and network-dependent', score 14.

Static review · not runListed 2026-09-18

Read the FMRS scoring method →

Fit and risk

What it can accessUses the network

Best for

  • Individuals planning train travel within China
  • Developers who want 12306 query capabilities inside MCP clients such as Claude Desktop or Cursor
  • Teams that need a self-hosted remote HTTP MCP service or Docker deployment
  • Developers studying MCP server implementations

Not for

  • Scenarios needing official booking, rebooking, refunds or payment (this project is query-only)
  • Commercial use or production systems with availability/SLA requirements
  • Mission-critical workloads that cannot tolerate upstream API changes or volatility
  • Users expecting official 12306 support or endorsement

Required permissions

  • Network access: must be able to reach the official 12306 endpoints
  • Local file reads: loads bundled static resources such as station data
  • HTTP mode port binding: listens on 0.0.0.0:8000 by default
  • Reads a .env file in the project root when used

Risks and side effects

  • Unofficial third-party project that only aggregates and relays 12306 public endpoints; upstream changes or rate limits can break queries
  • The README explicitly states it is for learning and research only and prohibits commercial use; users bear the consequences of use
  • Binding HTTP to 0.0.0.0 may expose the port to other hosts on the network, and no authentication mechanism is described
  • Frequent upstream calls may trigger rate limiting or affect the user's account
  • Results depend on upstream data and may be delayed or inaccurate, so they should not be the sole basis for decisions

Setup

Before you start

Runtime：Python 3.10+ · Docker

Other optional settings (4)
SERVER_HOST optional HTTP listen address, default 0.0.0.0; only needed for remote HTTP mode, set via env or .env.
SERVER_PORT optional HTTP listen port, default 8000; only needed for remote HTTP mode.
DEBUG optional Debug mode flag, default false, optional.
LOG_LEVEL optional Log level (DEBUG/INFO/WARNING/ERROR), default INFO, optional.
  1. Prepare the environment: Python >= 3.10, < 3.14, with network access to the official 12306 endpoints.
  2. Stdio mode (recommended for local clients): run uvx mcp-server-12306, or add {"mcpServers": {"12306": {"command": "uvx", "args": ["mcp-server-12306"]}}} to your client config; pip / pipx installs are also supported.
  3. Streamable HTTP mode: run mcp-12306 after installation, or uv run python scripts/start_server.py from source; the server listens on port 8000 by default and the client URL is http://localhost:8000/mcp.
  4. Docker deployment: docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest.
  5. Optional configuration: set SERVER_HOST (default 0.0.0.0), SERVER_PORT (default 8000), DEBUG (default false), LOG_LEVEL (default INFO) via environment variables or a .env file.
claude_desktop_config.json 
{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "12306": {
      "command": "uvx",
      "args": [
        "mcp-server-12306"
      ]
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add 12306 -- uvx mcp-server-12306

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After connecting, the client's tool list should show the seven tools such as query-tickets and search-stations; sending "search station Beijing" and getting station data confirms the install works.

Troubleshooting

  1. Verify Python is >= 3.10, < 3.14
  2. Verify the host can reach the official 12306 endpoints
  3. In Stdio mode, check that the command and args in the client config are correct (uvx / pipx / uv)
  4. In HTTP mode, call /health to check service status, loaded station count and active sessions
  5. In HTTP mode, call /schema/tools to confirm tool schemas load correctly
  6. On port conflicts, change SERVER_PORT and raise verbosity with DEBUG and LOG_LEVEL=DEBUG
  7. If station data looks wrong, run scripts/update_stations.py to update it

Things to try

Once connected, you can ask your AI assistant things like:

  • Check remaining high-speed tickets from Beijing to Shanghai for tomorrow
  • Search for the station Hangzhou East and show its telecode
  • List all stops and arrival times for train G1
  • Find transfer options from Guangzhou to Changsha the day after tomorrow

Tools 7

query-tickets read-only
One-stop query of remaining tickets, train numbers, seat classes and times, with optional train filtering
query-ticket-price read-only
Real-time query of ticket prices per train and seat class
search-stations read-only
Fuzzy station search by Chinese name, pinyin, initials or three-letter code
query-transfer read-only
Transfer/connection plan query returning the full route and waiting time
get-train-route-stations read-only
Query all stopover stations and arrival/departure times for a train
get-train-no-by-train-code read-only
Map a train code to its official unique train number
get-current-time read-only
Get the current time and relative dates to help pick a travel date

Use cases

Conversationally query train availability and seat classes for a given date and route in an AI assistant
Compare real-time prices across trains and seat classes for the same route
Search 3382+ stations by Chinese name, pinyin, initials or three-letter code
Find official transfer plans when no direct train exists
Inspect all stopover stations and arrival/departure times of a specific train
Get the current time and relative dates to help choose a travel date

Supported clients

Claude Desktop
Cursor

Listed from the project's documentation, not tested by this site.

Overview

12306 MCP Server is a high-performance train ticket query backend built on the Model Context Protocol (MCP). Through standardized interfaces it relays the official 12306 public data and exposes six query domains: remaining tickets, ticket prices, stations, train stopovers, transfers, and time. It is a third-party MIT-licensed open-source project, not an official 12306 product. It supports both Stdio transport for local clients and Streamable HTTP for remote deployment (default port 8000), with both transports sharing the same core instance, and it can also be deployed via Docker.

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 670 · Tools 11 Compare with this →
Compare with other MCP servers

Source revision f6865c077cfd Data synced 2026-11-02 Read the FMRS scoring method