Skip to main content
Glama
12306 MCP Server

12306 MCP Server

by drfccv

🚄 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 助手、自动化脚本、智能终端等场景。


📑 目录


Related MCP server: 12306 Train Ticket Search MCP Server

✨ 功能特性

类别

能力

🎫 余票查询

余票 / 车次 / 座席 / 时刻一站式查询,支持按车次过滤

💰 票价查询

实时查询各车次各席别票价(商务座 → 无座全覆盖)

🏙️ 车站搜索

全国 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 客户端。

安装:

# uvx(推荐,环境隔离)
uvx mcp-server-12306

# 或 pip / pipx
pip install mcp-server-12306

客户端配置(如 claude_desktop_config.json):

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

pipx:

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

本地源码(开发者调试):

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync
{
  "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 结束会话。

启动:

# 安装后直接启动
mcp-12306

# 或本地源码启动
uv run python scripts/start_server.py

客户端配置:

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

内置 HTTP 端点:

端点

方法

说明

/mcp

POST / GET / DELETE

MCP Streamable HTTP 协议入口

/health

GET

健康检查(含已加载车站数、活跃会话数)

/schema/tools

GET

全部工具 JSON Schema

/

GET

服务信息(版本、协议版本、端点)

方式三:Docker 部署

# 拉取镜像并运行(默认端口 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_HOST

0.0.0.0

HTTP 监听地址

SERVER_PORT

8000

HTTP 监听端口

DEBUG

false

调试模式

LOG_LEVEL

INFO

日志级别(DEBUG / INFO / WARNING / ERROR)

# 示例:.env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
LOG_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                   # 依赖锁文件

🧑‍💻 开发指南

# 1. 克隆并初始化
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

# 2. 类型检查(mypy,严格模式)
uv run mypy src scripts

# 3. 代码格式化
uv run black src scripts
uv run isort src scripts

# 4. 构建与发布
uv run python -m build
uv 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 官方相关规定,合理合规使用。


📄 License

MIT © Drfccv


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

Available Tools

7 tools
get-current-timeC

获取当前日期和时间信息,支持相对日期计算。返回当前日期、时间,以及常用的相对日期。

Inputs: timezone, format.

get-train-no-by-train-codeB

车次号转官方唯一编号(train_no),支持三字码/全名。常用于经停站查询前置转换。

Inputs: train_code (required), from_station (required), to_station (required), train_date (required).

get-train-route-stationsA

列车经停站全表查询。支持输入车次号或官方编号,返回所有经停站、到发时刻、停留时间。

Inputs: train_no (required), from_station (required), to_station (required), train_date (required).

query-ticket-priceA

查询火车票价信息。输入出发站、到达站、日期,返回各车次的票价详情。支持指定车次号过滤。

【智能筛选指南】返回结果通常包含出发/到达城市的所有相关车站(如北京/北京西/北京南)。请根据用户输入语境灵活处理:

  1. 用户仅输入城市名(如'九江'):请展示所有相关站点的车次,不要过滤。

  2. 用户指定具体车站(如'九江站'):优先展示匹配车站的车次,但若其他同城车站有更优方案(如时间更短、有票),也应作为补充选项提供。 请避免机械地仅通过字符串匹配过滤车次,以免遗漏用户可能感兴趣的出行方案。

Inputs: from_station (required), to_station (required), train_date (required), train_code, +1 more.

query-ticketsA

官方12306余票/车次/座席/时刻一站式查询。输入出发站、到达站、日期,返回所有可购车次、时刻、历时、各席别余票等详细信息。支持中文名、三字码。

【智能筛选指南】返回结果通常包含出发/到达城市的所有相关车站(如北京/北京西/北京南)。请根据用户输入语境灵活处理:

  1. 用户仅输入城市名(如'九江'):请展示所有相关站点的车次,不要过滤。

  2. 用户指定具体车站(如'九江站'):优先展示匹配车站的车次,但若其他同城车站有更优方案(如时间更短、有票),也应作为补充选项提供。 请避免机械地仅通过字符串匹配过滤车次,以免遗漏用户可能感兴趣的出行方案。

Inputs: from_station (required), to_station (required), train_date (required).

query-transferA

官方中转换乘方案查询。输入出发站、到达站、日期,可选中转站/无座/学生票,自动分页抓取全部中转方案。

Inputs: from_station (required), to_station (required), train_date (required), middle_station, +2 more.

search-stationsA

智能车站搜索。支持中文名、拼音、简拼、三字码(Code)。可用于模糊搜索(如“北京”),也可用于精确获取车站代码(如输入“BJP”返回北京站信息)。

Inputs: query (required), limit.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: get-current-time provides time/date info, get-train-no-by-train-code converts train codes, get-train-route-stations shows station stops, query-ticket-price gives pricing, query-tickets shows availability, query-transfer finds connections, and search-stations locates stations. The descriptions clearly differentiate their functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun or verb-noun-noun pattern using snake_case (e.g., get-current-time, query-ticket-price, search-stations). There are no deviations in naming style, making the set predictable and readable.

    Tool Count5/5

    With 7 tools, this server is well-scoped for a 12306 train service domain. Each tool serves a specific, non-redundant function, covering core operations like time lookup, code conversion, station search, route details, pricing, ticket availability, and transfers, which is appropriate for this use case.

    Completeness4/5

    The tool set provides comprehensive coverage for querying train information, including time, routes, prices, tickets, transfers, and stations. Minor gaps might include operations like booking tickets or managing user accounts, but these are likely outside the server's intended query-focused scope, and agents can work effectively with the provided tools.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that allows large language models to search for and analyze Chinese railway (12306) tickets through a simple API interface.
      8
      19
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      12306 ticket purchase search server based on Model Context Protocol (MCP). It provides a simple API interface, allowing large models to search for 12306 ticket purchasing information through the interface.
      8
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables querying train and high-speed rail schedules, durations, and seat availability between Chinese stations using 12306 data, with automatic fallback to simulated data when the API is rate-limited.
      -