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": {}
    }
  }
}

界面配置方式：

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-tickets 参数

代理配置

如需使用 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 的使用条款。