# 12306-MCP 车票查询工具

[魔搭部署指南](./docs/model-scope-deploy.md) ｜ [实现原理](./docs/principle.md) ｜ [架构说明](./docs/architecture.md)

12306-MCP 是基于 Model Context Protocol（MCP）的 12306 车票信息查询服务。它把 12306 的余票、车次、车站与中转查询封装成标准 MCP 工具，供支持 MCP 的 AI 客户端（Cursor、Cherry Studio、通义灵码、Claude 等）通过 Stdio 或 SSE / Streamable HTTP 远程调用。

## 功能

- 查询指定日期两地之间的 12306 车票余票与票价
- 查询车次的具体经停站、到发时刻与历时
- 城市 / 站名 / 站码（telecode）互查
- 中转方案查询
- 输出格式支持 text / csv / json

内置工具：

| 工具 | 说明 |
| --- | --- |
| `get-current-date` | 获取上海时区（Asia/Shanghai）当前日期 |
| `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` | 查询车次经停站信息 |

## 本地使用（Stdio）

环境要求：Node.js 18 及以上。

```bash
npm ci
npm start
```

在 MCP 客户端配置：

```json
{
  "mcpServers": {
    "12306-mcp": {
      "command": "node",
      "args": ["/绝对路径/build/index.js"]
    }
  }
}
```

也可以直接运行已发布的 npm 包：

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

## 远程使用（SSE / Streamable HTTP）

本地启动 HTTP 服务：

```bash
npm run start:http
```

默认监听 `0.0.0.0:8080`（可通过 `--host`、`--port` 或环境变量 `HOST`、`PORT` 修改）：

- Streamable HTTP：`POST /mcp`
- SSE：`GET /sse`，消息回传 `POST /message`

部署到魔搭（ModelScope）MCP 广场时，推荐选择 **Stdio/npx 托管方式**，平台会自动生成独立的 SSE 地址，无需自己维护 HTTP 服务。创建页面各项填法、可直接复制的“服务介绍”、以及三种部署方式的配置 JSON，见 [魔搭部署指南](./docs/model-scope-deploy.md)。

## Docker

```bash
docker build -t 12306-mcp .

# HTTP/SSE 模式
docker run -d -p 8080:8080 12306-mcp

# Stdio 模式
docker run --rm -it 12306-mcp node build/index.js
```

## 注意事项

- 本服务无需注册 12306 账号，也无需 API Key。
- 服务进程启动时需要访问 `kyfw.12306.cn` 等 12306 站点拉取车站表与查询路径；请确保运行环境（尤其云实例）能访问 12306。
- 12306 接口存在限流与反爬策略，仅供学习与研究使用，请勿高频滥用。

## 参考

- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- 上游项目：[Joooook/12306-mcp](https://github.com/Joooook/12306-mcp)

## License

MIT