MCP Server 12306

Name: MCP Server 12306
Author: drfccv

Looks up China Railway 12306 train schedules, seat availability, fares, stops and transfers

By drfccv (individual) Python Local · stdio, Streamable HTTP Maps and travel

GitHub PyPI Website

58 popularity score ★ 421 ↓ 1.3k/mo

Connect your client

Local (once it is running)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add --transport http 12306 http://localhost:8000/mcp

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "12306": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.12306]
url = "http://localhost:8000/mcp"

Gemini CLITerminal

gemini mcp add --scope user --transport http 12306 http://localhost:8000/mcp

Local (PyPI)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

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

Claude Desktopclaude_desktop_config.json

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

Cursor~/.cursor/mcp.json

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

VS Code.vscode/mcp.json

{
  "servers": {
    "12306": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-server-12306"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.12306]
command = "uvx"
args = ["mcp-server-12306"]

Gemini CLITerminal

gemini mcp add --scope user 12306 uvx -- mcp-server-12306

Local (from source)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

FirstTerminal

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

Claude CodeTerminal

claude mcp add 12306 -- uv --directory '<ABSOLUTE_PATH_TO_CLONE>' run mcp-server-12306

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "12306": {
      "command": "uv",
      "args": [
        "--directory",
        "<ABSOLUTE_PATH_TO_CLONE>",
        "run",
        "mcp-server-12306"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "12306": {
      "command": "uv",
      "args": [
        "--directory",
        "<ABSOLUTE_PATH_TO_CLONE>",
        "run",
        "mcp-server-12306"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "12306": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "<ABSOLUTE_PATH_TO_CLONE>",
        "run",
        "mcp-server-12306"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.12306]
command = "uv"
args = ["--directory", "<ABSOLUTE_PATH_TO_CLONE>", "run", "mcp-server-12306"]

Gemini CLITerminal

gemini mcp add --scope user 12306 uv -- --directory '<ABSOLUTE_PATH_TO_CLONE>' run mcp-server-12306

Settings 4

`SERVER_HOST`	Optional: Address the HTTP mode listens on; 0.0.0.0 by default.
`SERVER_PORT`	Optional: Port the HTTP mode listens on; 8000 by default.
`LOG_LEVEL`	Optional: DEBUG, INFO, WARNING or ERROR; INFO by default.
`DEBUG`	Optional: Turns on debug mode; false by default.

What it does

MCP Server 12306 connects an assistant to the public query endpoints of 12306, the ticketing system of China Railway. It can check which trains run between two stations on a given date and how many seats are left in each class, look up fares, find stations by Chinese name, pinyin, pinyin initials or three-letter code, list every stop of a train with arrival and departure times, and fetch the transfer itineraries 12306 itself suggests. A small time tool gives the current date in a chosen time zone so the assistant can work out dates like "next Friday".

It only queries; it does not log in, book or pay. The station list ships inside the package, so station searches work offline, while ticket, fare, route and transfer lookups call kyfw.12306.cn directly from your machine.

The package installs two programs: mcp-server-12306 talks over stdio for local clients, and mcp-12306 starts a Streamable HTTP server (port 8000 by default) that also exposes /health and /schema/tools. A Docker image runs the HTTP mode.

In the code at version 0.5.0.post20260930, every 12306 request is retried up to 3 times on network errors with an 8-second timeout, and the HTTP client is created with TLS certificate checking turned off (verify=False in services/ticket_service.py), something the README does not mention.

What it needs

Runtime	Python 3.10+

Python 3.10 to 3.13 (3.14 is excluded by the package) and uv for the uvx command, or pip/pipx. Network access to kyfw.12306.cn. No account or key. For the Docker image: Docker, then start it with port 8000 published and point the client at http://localhost:8000/mcp.

Limits

Queries only: no booking, payment, login or order lookups. Dates in the past are refused for ticket, train-number and route lookups. search-stations returns 10 results by default, at most 50 with limit. It depends on unofficial use of 12306's web endpoints, which can change or block requests without notice. Its own disclaimer says it is for study and research, forbids commercial use (despite the MIT licence file), and puts any account ban or legal risk on the user. The Docker image and mcp-12306 bind to 0.0.0.0 unless SERVER_HOST is set.

Who it suits

Suits someone planning train trips in mainland China who wants an assistant to compare trains, seat availability, fares and transfers in one conversation, run locally with no keys. It is not a booking tool; buying still happens in 12306 itself. Those who need commercial use should note the maker's no-commercial-use disclaimer, and anyone worried about TLS checks being off should run it on a trusted network.

Tools 7

query-tickets: Lists trains between two stations on a date with seat counts per class and times, optionally filtered by train
query-ticket-price: Gets fares per seat class for trains on a route and date, adult or student
search-stations: Finds stations by Chinese name, pinyin, initials or three-letter code
query-transfer: Fetches 12306's suggested one-change itineraries with waiting times, optionally via a chosen station
get-train-route-stations: Lists every stop of a train with arrival and departure times
get-train-no-by-train-code: Converts a train code such as G1 into 12306's internal train number
get-current-time: Returns the current date and time in a time zone, Asia/Shanghai by default

Popularity

58 popularity score, on our list (the bar is 36)

★ 421 ↓ 1.3k/mo

GitHub stars	421	31.5 points
Stars in 30 days	+15	6 points
PyPI downloads, last month	1,318	20.2 points

Measured 2026-11-07. How the score works.

Where it is published

Code	drfccv/mcp-server-12306 ★ 421
PyPI	mcp-server-12306 0.5.0.post20261103, 2026-11-05, the one the command runs
Docker Hub	drfccv/mcp-server-12306

What it can reach

Runs	On your machine
Reaches	The internet
Changes things	No: it reads only
Sign-in	None
Licence	MIT (PyPI)
Last code change	2026-11-05

Runs on your machine and sends requests only to kyfw.12306.cn, posing as a desktop Chrome browser; no account, cookie or key of yours is used. No tool writes or changes anything. TLS certificate verification is turned off for those requests (verify=False in ticket_service.py), so a party on the network path could alter responses. The HTTP mode and Docker image listen on 0.0.0.0:8000 by default with no authentication; set SERVER_HOST=127.0.0.1 to keep it local. The maker's disclaimer warns that use may breach 12306 rules and that account bans or legal risk fall on the user.

Over time

GitHub stars 421 +15 (+4 %)

421406

9 Oct 20267 Nov 2026

PyPI downloads a month 1.3k +548 (+71 %)

3.1k770

13 May 20267 Nov 2026

Before the site measured it, read from pypistats' daily download counts.

Popularity score 58 +6 (+12 %)

5852

9 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-15.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![MCP Server 12306 on EveryMCPServer](https://everymcpserver.com/badge/mcp-server-12306.svg)](https://everymcpserver.com/servers/mcp-server-12306)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 4

What it does

What it needs

Limits

Who it suits

Tools 7

Similar servers

Mapbox MCP Server

Daiso MCP

Google Maps MCP Server

MCP Linear

PostgreSQL MCP Server

MCPQL