12306-mcp：基于MCP协议的火车票查询服务器

12306-mcp 是一个基于 Model Context Protocol (MCP) 的火车票查询服务器，专为查询中国铁路12306票务信息设计。它提供简单易用的 API 接口，让用户或开发者通过程序快速获取实时火车票信息。项目托管在 GitHub，由开发者 Joooook 创建，旨在为 AI 助手或自动化工具提供高效的票务查询支持。服务器支持查询余票、列车信息、经停站和中转方案，适合需要快速获取票务数据的场景。项目仅用于学习，强调不存储或篡改官方数据，注重接口的简洁性和实用性。

功能列表

• 查询12306火车票信息，包括余票、车次、座位类型和时刻表。
• 过滤列车信息，支持按时间、票价或车次类型筛选。
• 查询列车经停站信息，获取途经城市和停靠时间。
• 支持中转查询，提供一站式换乘方案建议。
• 提供简单的 API 接口，方便集成到 AI 助手或自动化程序。
• 支持模糊搜索全国车站信息，便于快速定位车站。

使用帮助

安装流程

要使用 12306-mcp 服务器，需按照以下步骤在本地或服务器上部署：

1. 克隆项目代码
   使用 Git 命令下载项目源码：

   git clone https://github.com/Joooook/12306-mcp.git
   

2. 安装依赖
   进入项目目录并安装 Node.js 依赖：

   cd 12306-mcp
   npm i
   

3. 构建项目
   运行构建命令生成可执行文件：

   npm run build
   

4. 启动服务器
   执行以下命令启动服务器：

   node ./build/index.js
   

5. 配置 MCP 服务器
   如果需要将 12306-mcp 集成到支持 MCP 协议的系统中，需在配置文件中添加以下内容：

   {
   "mcpServers": {
   "12306-mcp": {
   "command": "npx",
   "args": ["-y", "12306-mcp"]
   }
   }
   }
   

   配置文件路径通常位于 MCP 协议支持的客户端或平台中，具体路径请参考目标系统的文档。

使用方法

部署完成后，12306-mcp 提供了一组 API 接口，开发者或 AI 助手可以通过 HTTP 请求调用。以下是主要功能的操作流程：

1. 查询火车票信息

用户可以通过 API 发送请求，查询指定日期、出发地和目的地的火车票信息。例如，查询从北京到上海的火车票：

• API 请求示例：

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22
  

• 返回数据：JSON 格式，包含车次、出发时间、到达时间、票价、余票数量等。
• 操作步骤：
  1. 确定出发地、目的地和日期。
  2. 使用 HTTP 客户端（如 Postman）或代码发送 GET 请求。
  3. 解析返回的 JSON 数据，获取可用车次和票价。
• 注意：出发地和目的地需使用12306官方车站名称或代码，支持模糊搜索。

2. 过滤列车信息

用户可根据需求筛选列车，例如只查看高铁或夜间列车：

• API 请求示例：

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22&type=highspeed
  

• 操作步骤：
  1. 在请求中添加筛选参数，如 type=highspeed（高铁）或 time=night（夜间）。
  2. 服务器返回符合条件的车次列表。
  3. 用户可进一步根据票价或时长排序。

3. 查询经停站

查询某车次的途经站点和停靠时间：

• API 请求示例：

  GET /train/stops?trainNo=G123
  

• 返回数据：JSON 格式，包含途经站点的名称、到达时间和停留时间。
• 操作步骤：
  1. 获取目标车次号（如 G123）。
  2. 发送请求，获取经停站列表。
  3. 可结合地图工具生成旅行攻略，规划途经城市行程。

4. 中转查询

对于没有直达车次的路线，服务器提供中转方案：

• API 请求示例：

  GET /transfer?from=Xian&to=Zhengzhou&date=2025-07-22
  

• 返回数据：推荐中转站、换乘时间和总行程时长。
• 操作步骤：
  1. 输入出发地、目的地和日期。
  2. 服务器返回中转方案，如在武汉换乘的具体车次和时间。
  3. 用户可根据总时长或票价选择最优方案。

5. 模糊搜索车站

支持输入部分车站名称查找完整信息：

• API 请求示例：

  GET /stations?name=Hang
  

• 返回数据：包含“杭州”“杭州东”等车站的详细信息。
• 操作步骤：
  1. 输入车站名称的部分拼音或汉字。
  2. 服务器返回匹配的车站列表。
  3. 从列表中选择正确的车站代码用于票务查询。

注意事项

• 数据来源：所有票务数据来自12306官方接口，服务器仅作聚合和转发，不存储数据。
• 使用风险：频繁请求可能触发12306的反爬机制，建议合理设置请求频率。
• 开发支持：项目欢迎开发者贡献新功能，可通过 GitHub 提交 feature 请求。

应用场景

1. AI 助手集成
   12306-mcp 可嵌入 AI 助手（如智能聊天机器人），用户通过语音或文字输入“明天从上海到杭州的火车票”，助手调用 API 返回实时票务信息，快速提供车次和票价。
2. 旅行规划工具
   开发者可将 12306-mcp 集成到旅行规划应用，结合经停站信息生成途经城市的旅游攻略。例如，查询北京到广州的列车，推荐途经武汉的景点。
3. 自动化票务查询
   企业可使用 12306-mcp 开发自动化票务监控工具，实时跟踪某线路的余票情况，适合差旅管理或票务代理场景。
4. 教育与研究
   学生或开发者可利用 12306-mcp 学习 MCP 协议的实现，研究如何通过 API 聚合第三方数据，适合计算机课程或开源项目实践。

QA

1. 12306-mcp 是否需要付费？
   该项目完全开源，免费使用，托管在 GitHub 上，仅需自行部署服务器。
2. 是否支持实时票务更新？
   是的，服务器通过12306官方接口获取实时数据，确保票务信息准确。
3. 如何避免触发12306的反爬机制？
   建议设置合理的请求间隔（如每分钟不超过5次），避免短时间内高频请求。
4. 可以直接在手机上使用吗？
   目前需部署在电脑或服务器上，手机可通过 API 客户端访问，或等待未来可能的移动端适配。
5. 支持哪些编程语言调用 API？
   API 使用标准 HTTP 协议，任何支持 HTTP 请求的语言（如 Python、JavaScript）均可调用。