12306-search

一个基于 MCP (Model Context Protocol) 的 12306 火车票查询服务，让 AI 助手能够帮你查询火车票信息。

功能特性

• 🚄 余票查询 - 查询指定日期、出发站、到达站的火车票信息
• 🔄 中转查询 - 查询需要换乘的火车票方案
• 🛤️ 经停站查询 - 查询特定车次的所有经停站信息
• 🏙️ 车站查询 - 按城市名或车站名查询车站代码
• 🔍 智能筛选 - 支持按车次类型、出发时间、排序方式等筛选
• 🌐 代理支持 - 支持 SOCKS5 代理访问

安装

# 克隆项目
git clone https://github.com/xuqssq/12306-search.git
cd 12306-search

# 安装依赖
yarn install
# 或
npm install

使用方式

1. 作为 MCP 服务器（推荐）

在支持 MCP 的客户端（如 Claude Desktop、Cherry Studio、Cursor 等）中配置：

JSON 配置方式：

{
  "mcpServers": {
    "12306": {
      "command": "node",
      "args": ["/path/to/12306-search/main.js"],
      "env": {}
    }
  }
}

界面配置方式：

字段	值
名称	12306
类型	标准输入/输出 (stdio)
命令	node
参数	/path/to/12306-search/main.js

2. HTTP/SSE 模式

# 启动 HTTP 服务器
node main.js --port 3000

# 或指定主机
node main.js --host 0.0.0.0 --port 3000

3. Stdio 模式

node main.js

可用工具

工具名	描述
get-current-date	获取当前日期（上海时区）
get-stations-code-in-city	查询城市内所有车站
get-station-code-of-citys	查询城市代表车站代码
get-station-code-by-names	按车站名查询代码
get-station-by-telecode	按代码查询车站详情
get-tickets	查询余票信息
get-interline-tickets	查询中转票信息
get-train-route-stations	查询列车经停站

查询参数说明

get-tickets 参数

参数	类型	必填	说明
date	string	是	查询日期，格式 yyyy-MM-dd
fromStation	string	是	出发站代码
toStation	string	是	到达站代码
trainFilterFlags	string	否	车次筛选：G(高铁)、D(动车)、Z(直达)、T(特快)、K(快速)、O(其他)、F(复兴号)、S(智能动车组)
earliestStartTime	number	否	最早出发时间 (0-24)
latestStartTime	number	否	最晚出发时间 (0-24)
sortFlag	string	否	排序方式：startTime、arriveTime、duration
sortReverse	boolean	否	是否逆序
limitedNum	number	否	返回数量限制
format	string	否	输出格式：text、csv、json

代理配置

如需使用 SOCKS5 代理，可通过环境变量配置：

# 设置代理
export SOCKS_PROXY_URL="socks5h://username:password@host:port"

# 禁用代理
export SOCKS_PROXY_URL=""

或在 MCP 配置中添加环境变量：

{
  "mcpServers": {
    "12306": {
      "command": "node",
      "args": ["/path/to/12306-search/main.js"],
      "env": {
        "SOCKS_PROXY_URL": "socks5h://127.0.0.1:1080"
      }
    }
  }
}

项目结构

12306-search/
├── main.js              # 主入口，MCP 服务器
├── lib/
│   ├── api.js           # HTTP 请求封装
│   ├── constants.js     # 常量定义
│   ├── filter.js        # 过滤和排序
│   ├── formatter.js     # 输出格式化
│   ├── parser.js        # 数据解析
│   ├── proxy.js         # SOCKS5 代理支持
│   └── stations.js      # 车站数据管理
├── package.json
└── README.md

依赖

• @modelcontextprotocol/sdk - MCP SDK
• commander - CLI 参数解析
• date-fns / date-fns-tz - 日期处理
• mcp-http-server - HTTP/SSE 传输支持
• socks - SOCKS5 代理支持
• undici - HTTP 客户端
• zod - 参数验证

示例对话

配置好 MCP 服务器后，你可以这样与 AI 对话：

用户：帮我查一下明天北京到上海的高铁票

AI：（自动调用 get-current-date、get-station-code-of-citys、get-tickets 工具）

查询结果：

• G1 北京南 -> 上海虹桥 06:36 -> 12:40 历时：6:04
  • 商务座: 剩余5张票 1748元
  • 一等座: 有票 933元
  • 二等座: 有票 553元
• ...

许可证

MIT License

致谢

• 数据来源：12306
• 参考项目：Joooook/12306-mcp

免责声明

本项目仅供学习和研究使用，请勿用于商业用途。使用本项目查询的数据来自 12306 官方网站，请遵守相关法律法规和 12306 的使用条款。