🚄 mcp-server-12306 技能介绍

技能简介

mcp-server-12306 是基于 Model Context Protocol（MCP）的高性能火车票查询服务，将 12306 官方余票查询能力封装为标准 MCP 工具，供 AI 助手直接调用。项目使用 Python 3.10+ 开发，基于 MCP SDK v2，支持 Stdio 和 Streamable HTTP 两种传输模式，同时兼容 2025 版和 2026 版 MCP 协议。在 GitHub 已收获 377 颗星标，是一个活跃度高、社区认可度强的实用型 MCP 服务器。

核心能力

• 余票实时查询：支持按出发地、目的地、日期查询余票，返回车次、座席、票价等完整信息
• 票价智能查询：实时获取任意车次任意席别票价，从商务座到无座全覆盖
• 车站模糊搜索：全国 3382+ 车站数据，支持中文、拼音、简拼、三字码模糊匹配
• 中转换乘方案：自动抓取 12306 官方换乘方案，返回完整路径与等待时间
• 列车经停查询：查询指定列车的全部经停站及到发时刻
• 时间工具：获取任意时区当前时间、相对日期计算，辅助选择出行日期
• 双传输模式：同一核心实例同时支持 Stdio（本地）和 Streamable HTTP（远程），行为完全一致

安装配置

环境要求

• Python >= 3.10, < 3.14
• 推荐使用 uv 包管理器（环境隔离、安装快）

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

# 安装
uvx mcp-server-12306

# 或 pip
pip install mcp-server-12306

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

# 安装后启动
mcp-12306
# 服务默认监听 http://localhost:8000/mcp

方式三：Docker 部署

docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

使用步骤

1. 安装服务：根据上述方式完成安装（uvx / pip / Docker）
2. 配置客户端：在 Claude Desktop 或其他 MCP 客户端的配置文件（如 claude_desktop_config.json）中添加服务配置
3. 重启 AI 助手：使配置生效，AI 助手将自动加载 MCP 工具
4. 自然语言查询：直接用自然语言向 AI 助手提问，如"帮我查一下明天北京到上海的高铁票"
5. 获取结果：AI 助手自动调用 query-tickets 等工具，返回完整车次、票价、余票信息

适用场景

• 差旅规划：查询两地间余票和票价，快速制定出行方案
• 智能客服：在 AI 客服系统中集成 12306 查询能力，自动回答车次票价问题
• 出行助手：作为个人 AI 助手的出行技能，随时查询火车票务信息
• 自动化脚本：在服务器端部署 HTTP 模式，供内部系统调用查询
• 旅游平台集成：在旅游产品系统中嵌入实时火车票查询能力
• 数据分析：结合经停站数据做铁路线路分析或出行规律研究

适用人群

• 需要在 AI 助手中集成火车票查询能力的开发者
• 经常出差且需要快速查询火车票的商务人士
• 建设 AI 出行助手或旅游平台的团队
• 研究 MCP 协议和 AI 工具集成的技术学习者

工作原理

mcp-server-12306 采用 MCP SDK v2 构建，核心架构分为传输层和业务层两层。传输层支持 Stdio 和 HTTP 两种协议，调用同一核心业务实例，保证两种模式行为完全一致。业务层封装了对 12306 官方接口的调用，包括余票查询（query-tickets）、票价查询（query-ticket-price）、车站搜索（search-stations）、中转换乘（query-transfer）、经停查询（get-train-route-stations）等 7 个 MCP 工具。网络请求统一走 _request_with_retry，具备自动重试和会话保持能力。车站数据预加载于 station_name.js 文件中（3382+ 站），避免每次查询重复拉取。项目代码结构清晰，server.py 为传输无关的核心模块，services/ 目录下的 station_service.py 和 ticket_service.py 分别处理车站数据和票务逻辑。

官方链接

• GitHub：https://github.com/drfccv/mcp-server-12306
• PyPI：https://pypi.org/project/mcp-server-12306/
• Docker Hub：https://hub.docker.com/r/drfccv/mcp-server-12306