🚄 MCP Server 12306

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

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

📑 目录

✨ 功能特性
🚀 快速开始
🛠️ 工具一览
⚙️ 配置项
🏗️ 项目结构
🧑‍💻 开发指南
📚 详细文档
⚠️ 免责声明
📄 License

✨ 功能特性

类别	能力
🎫 余票查询	余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤
💰 票价查询	实时查询各车次各席别票价（商务座 → 无座全覆盖）
🏙️ 车站搜索	全国 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 / pipx
pip install mcp-server-12306

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

config.json

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

其他安装方式（点击展开）

pipx：

config.json

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

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

bash

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

config.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

客户端配置：

config.json

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

内置 HTTP 端点：

端点	方法	说明
`/mcp`	POST / GET / DELETE	MCP Streamable HTTP 协议入口
`/health`	GET	健康检查（含已加载车站数、活跃会话数）
`/schema/tools`	GET	全部工具 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_HOST`	`0.0.0.0`	HTTP 监听地址
`SERVER_PORT`	`8000`	HTTP 监听端口
`DEBUG`	`false`	调试模式
`LOG_LEVEL`	`INFO`	日志级别（`DEBUG` / `INFO` / `WARNING` / `ERROR`）

bash

# 示例：.env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
LOG_LEVEL=INFO

🏗️ 项目结构

Code

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.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 官方数据，仅作为官方公开接口的智能聚合与转发。
使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
请遵守中国法律法规及 12306 官方相关规定，合理合规使用。

📄 License

MIT © Drfccv

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