# MCP 12306 火车票

> 12306 火车票查询、余票查询、车次查询工具。基于MCP协议的官方火车票查询服务，支持实时票价、余票、车次时刻等信息查询。

- Skill: `caoronglin/mcp-12306` (Agent Skill)
- Install (CLI): `npx skillmds@latest add caoronglin/mcp-12306`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caoronglin/mcp-12306/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: caoronglin (https://skillmd.com/u/caoronglin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caoronglin/mcp-12306

---


# 12306 火车票查询 MCP 技能

## 功能说明

12306 MCP Server 提供中国铁路12306官方网站的火车票查询功能：

- 🚄 **车次查询**：查询两站之间的所有车次
- 💺 **余票查询**：实时查询各座位类型的余票情况
- 💰 **票价查询**：获取各座位类型的票价信息
- ⏰ **时刻表**：查询列车发车和到达时间
- 🔄 **中转查询**：支持中转方案推荐

## 工具列表

### 1. search_trains - 车次查询

**功能描述**：查询指定日期两站之间的所有车次

**参数说明**：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| from_station | string | ✅ | 出发站（站名或电报码） |
| to_station | string | ✅ | 到达站（站名或电报码） |
| date | string | ✅ | 出发日期（YYYY-MM-DD） |
| purpose_codes | string | ❌ | 票种：ADULT（成人）/ STUDENT（学生） |

**使用示例**：
```json
{
  "from_station": "北京",
  "to_station": "上海",
  "date": "2026-03-10",
  "purpose_codes": "ADULT"
}
```

### 2. query_ticket - 余票查询

**功能描述**：查询指定车次的余票情况

**参数说明**：

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| train_no | string | ✅ | 车次号 |
| from_station | string | ✅ | 出发站 |
| to_station | string | ✅ | 到达站 |
| date | string | ✅ | 出发日期 |

**返回字段**：
- 各座位类型的余票数量（商务座、一等座、二等座等）
- 座位类型代码和名称
- 是否可购买标志

### 3. get_station_code - 站点代码查询

**功能描述**：获取站点名称对应的电报码

**参数**：
- `station_name`: 站点名称

**用途**：车次查询需要使用站点电报码

## 配置方式

### 方式一：NPX 运行（推荐）
```json
{
  "mcpServers": {
    "12306-mcp": {
      "command": "npx",
      "args": ["-y", "12306-mcp"]
    }
  }
}
```

### 方式二：HTTP 服务模式
```bash
npx -y 12306-mcp --port 3000
```

```json
{
  "mcpServers": {
    "12306-mcp": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

### 方式三：Docker 部署
```bash
docker run -i --rm 12306-mcp
```

## 使用场景

### 1. 查询车次
```
用户：帮我查一下明天从北京到上海的高铁
助手：[调用 search_trains 工具查询车次列表]
```

### 2. 查看余票
```
用户：G1次列车还有票吗？
助手：[调用 query_ticket 查询余票情况]
```

### 3. 学生票查询
```
用户：帮我查学生票
助手：[设置 purpose_codes=STUDENT 查询]
```

## 触发时机
- 用户询问火车票、高铁相关信息
- 需要查询列车时刻表
- 需要了解余票情况
- 计划出行需要购票信息

## 座位类型说明

| 代码 | 名称 | 说明 |
|------|------|------|
| SWZ | 商务座 | 最高级别座位 |
| ZY | 一等座 | - |
| ZE | 二等座 | 常见座位 |
| GR | 高级软卧 | 卧铺 |
| RW | 软卧 | 卧铺 |
| YW | 硬卧 | 卧铺 |
| RZ | 软座 | - |
| YZ | 硬座 | 最经济 |

## 最佳实践

### 1. 先查站点代码
```python
# 查询站点代码
station_code = get_station_code("北京西")  # 返回: BXP

# 使用站点代码查询车次
trains = search_trains(
    from_station="BXP",
    to_station="SHH",
    date="2026-03-10"
)
```

### 2. 日期格式
- 使用 YYYY-MM-DD 格式
- 可查询未来15天内的车票

### 3. 查询时机
- 早上8点更新最新数据
- 节假日票源紧张，建议提前查询

## 注意事项

⚠️ **重要提示**：
1. 本工具仅提供查询功能，不支持在线购票
2. 数据来源于12306官网，实时性可能有延迟
3. 节假日期间查询频率建议适度控制
4. 学生票需确认学生资质有效

## 常见问题

### Q: 查询返回空结果？
**A**: 可能原因：
- 日期超出可查询范围（15天内）
- 站点名称不正确
- 该日期无车次运行

### Q: 如何区分站点代码？
**A**: 使用 get_station_code 工具查询：
- 北京站 → BJP
- 北京西站 → BXP
- 上海站 → SHH
- 上海虹桥站 → AOHHQ

### Q: 余票显示"有"但无法购买？
**A**: 可能原因：
- 网络延迟导致数据未同步
- 车票已被其他用户锁定
- 需要登录12306账号才能购买

## 官方资源

- **项目地址**: https://github.com/Joooook/12306-mcp
- **许可证**: MIT License
- **维护状态**: 活跃维护中

---
*更新时间: 2026-03-08*
*版本: 1.0*