Mcp Server 12306

io.github.drfccvPublished by GitHub account drfccvv0.3.1Updated Oct 24, 2026

An MCP server that provides 12306 ticket query

VerifiedSTDIODesktop onlyLocation & LifestyleWeb Search & Scraping

Overview

AI-generated overview

A local MCP server that lets an assistant query China Railway 12306 train tickets, prices, stations, transfers and stop schedules.

What you can do
Query remaining tickets, train numbers, seat classes and departure times for a route and date, with optional filtering by train number and real-time fares per seat class for each train, plus official transfer itineraries with full paths and waiting times, and all stop stations and arrival/departure times for a given train, and look up the official unique number for a train code, and search the national station list by Chinese name, pinyin, initials or three-letter code, and get the current time in any time zone and relative date calculations to help pick a travel date.
When to use it
Useful when an assistant should help plan rail travel in China: checking availability and fares for a route and date, comparing direct trains with transfer options, or looking up station names and stop schedules.
Requirements
Runs locally as a Python package (Python 3.10 to below 3.14) via uvx, pip or pipx, or as a Docker image; network access to the official 12306 interfaces is required. An optional HTTP mode listens on port 8000 and is configured with SERVER_HOST, SERVER_PORT, DEBUG and LOG_LEVEL. No accounts or API keys are declared.
Before you install
The README states the project is for learning and research only, forbids commercial use, and that users bear all consequences, including possible account bans or legal risk. It forwards requests to official 12306 interfaces and does not store or alter official data. The HTTP mode defaults to listening on 0.0.0.0, so bind it to a local address if exposed.

Installation

In SourceWeft

  1. Open Mcp Server 12306 in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

🚄 MCP Server 12306

基于 Model Context Protocol (MCP) 的 12306 火车票查询服务

[PyPI - Version] [PyPI - Downloads] [Python - 3.10+] [Docker - Pulls] [License - MIT] [MCP - SDK v2] [Transport - Stdio/HTTP] [GitHub - Stars]


支持 余票 / 票价 / 车站 / 经停 / 换乘 / 时间 六大查询能力，开箱即用，适配 AI 助手、自动化脚本、智能终端等场景。

📑 目录

✨ 功能特性

类别能力
🎫 余票查询余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤
💰 票价查询实时查询各车次各席别票价（商务座 → 无座全覆盖）
🏙️ 车站搜索全国 3382+ 车站，支持中文 / 拼音 / 简拼 / 三字码模糊搜索
🔄 中转换乘官方换乘方案自动分页抓取，返回完整路径与等待时间
🛤️ 经停查询查询指定列车全部经停站与到发时刻
🕐 时间工具获取任意时区当前时间、相对日期计算，辅助选择出行日期
🔌 双传输模式Stdio（本地）| Streamable HTTP（远程），同一核心实例共享
🔄 协议自动协商基于 MCP SDK v2，自动兼容握手时代（2025-11-25）与现代协议（2026-07-28）

🚀 快速开始

环境要求

依赖要求
Python>= 3.10, < 3.14
包管理器uv（推荐）或 pip / pipx
网络可访问 12306 官方接口

💡 推荐使用 uv：环境隔离、安装快、锁文件管理依赖版本。

方式一：Stdio 模式（本地客户端推荐）

MCP Server 通过标准输入/输出与客户端通信，不占用网络端口，适合 Claude Desktop、Cursor 等本地 MCP 客户端。

安装：

bash
# uvx（推荐，环境隔离）uvx mcp-server-12306
# 或 pip / pipxpip install mcp-server-12306

客户端配置（如 claude_desktop_config.json）：

json
{  "mcpServers": {    "12306": {      "command": "uvx",      "args": ["mcp-server-12306"]    }  }}
其他安装方式（点击展开）

pipx：

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

本地源码（开发者调试）：

bash
git clone https://github.com/drfccv/mcp-server-12306.gitcd mcp-server-12306uv sync
json
{  "mcpServers": {    "12306": {      "command": "uv",      "args": ["--directory", "/path/to/mcp-server-12306", "run", "mcp-server-12306"]    }  }}

方式二：Streamable HTTP 模式（远程部署）

Server 启动 Web 服务（默认 8000 端口），通过 MCP Streamable HTTP 协议通信：POST 发送 JSON-RPC、GET 订阅流式响应、DELETE 结束会话。

启动：

bash
# 安装后直接启动mcp-12306
# 或本地源码启动uv run python scripts/start_server.py

客户端配置：

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

内置 HTTP 端点：

端点方法说明
/mcpPOST / GET / DELETEMCP Streamable HTTP 协议入口
/healthGET健康检查（含已加载车站数、活跃会话数）
/schema/toolsGET全部工具 JSON Schema
/GET服务信息（版本、协议版本、端点）

方式三：Docker 部署

bash
# 拉取镜像并运行（默认端口 8000）docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest
# 自定义端口docker run -d -p 8080:8000 \  -e SERVER_HOST=0.0.0.0 \  -e SERVER_PORT=8000 \  --name mcp-server-12306 \  drfccv/mcp-server-12306:latest

🛠️ 工具一览

工具名功能必填参数
query-tickets余票 / 车次 / 座席 / 时刻一站式查询from_station、to_station、train_date
query-ticket-price实时查询车次票价from_station、to_station、train_date
search-stations车站模糊搜索（中文 / 拼音 / 简拼 / 三字码）query
query-transfer中转换乘方案查询from_station、to_station、train_date
get-train-route-stations查询列车经停站及时刻表train_no、from_station、to_station、train_date
get-train-no-by-train-code车次号 → 官方唯一编号train_code、from_station、to_station、train_date
get-current-time当前时间与相对日期（辅助选日期）无

📖 每个工具的参数说明、返回示例、调用示例详见 📚 详细文档。

⚙️ 配置项

通过环境变量或项目根目录 .env 文件配置：

环境变量默认值说明
SERVER_HOST0.0.0.0HTTP 监听地址
SERVER_PORT8000HTTP 监听端口
DEBUGfalse调试模式
LOG_LEVELINFO日志级别（DEBUG / INFO / WARNING / ERROR）
bash
# 示例：.envSERVER_HOST=127.0.0.1SERVER_PORT=8000LOG_LEVEL=INFO

🏗️ 项目结构

mcp-server-12306/├── src/mcp_12306/            # 主包│   ├── server.py             # 核心 Server（工具注册与分发，双传输共享）│   ├── stdio_server.py       # Stdio 传输层 + CLI 入口│   ├── http_server.py        # Streamable HTTP 传输层 + HTTP 端点│   ├── services/             # 业务逻辑│   │   ├── station_service.py    # 车站数据服务（加载/搜索/编码转换）│   │   └── ticket_service.py     # 票务查询核心（7 个工具实现）│   ├── utils/                # 配置与日期工具│   │   ├── config.py             # pydantic-settings 配置│   │   └── date_utils.py         # 日期校验工具│   └── resources/            # 静态资源（车站数据 station_name.js）├── scripts/                  # 运维脚本│   ├── start_server.py       # HTTP 模式一键启动（环境自检）│   └── update_stations.py    # 更新车站数据├── docs/                     # 工具详细文档├── pyproject.toml            # 项目元数据 / 依赖 / 构建配置├── Dockerfile                # 多阶段构建（python:3.12-alpine）├── server.json               # MCP 注册表元数据└── uv.lock                   # 依赖锁文件

🧑‍💻 开发指南

bash
# 1. 克隆并初始化git clone https://github.com/drfccv/mcp-server-12306.gitcd mcp-server-12306uv sync
# 2. 类型检查（mypy，严格模式）uv run mypy src scripts
# 3. 代码格式化uv run black src scriptsuv run isort src scripts
# 4. 构建与发布uv run python -m builduv run twine upload dist/*

架构要点：

  • server.py 是传输无关的核心模块——工具注册（TOOL_HANDLERS）与业务分发（call_tool）都在此，stdio 与 HTTP 复用同一实例，保证两种模式行为完全一致。
  • 工具 Schema 单一来源于 ticket_service.MCP_TOOLS，HTTP 的 /schema/tools 端点与 MCP 工具列表同源。
  • 网络请求统一走 _request_with_retry（自动重试 + init 会话保持），业务错误与网络错误分离处理。

📚 详细文档

文档内容
query_tickets.md余票 / 车次 / 座席 / 时刻一站式查询
query_ticket_price.md实时票价查询
search_stations.md车站智能搜索
query_transfer.md中转换乘方案
get_train_route_stations.md列车经停站查询
get_current_time.md当前时间与相对日期

每份文档均包含：功能说明、实现方法、请求参数、返回示例与典型调用方式。

⚠️ 免责声明

  • 本项目仅供学习、研究与技术交流，严禁用于任何商业用途。
  • 本项目不存储、不篡改、不传播任何 12306 官方数据，仅作为官方公开接口的智能聚合与转发。
  • 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
  • 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。

📄 License

MIT © Drfccv

⭐ 如果这个项目对你有帮助，欢迎 Star 支持！

Source: README.md at commit 7993e3d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts