🚄 12306 MCP 服务器

---

✨ 项目简介

12306 MCP 服务器是一个基于模型上下文协议（MCP）的高性能火车票查询后端，支持官方12306剩余票数、车站、中转站、换乘查询以及智能时间工具，适用于AI/自动化/智能助手场景。它具有用户友好的界面，易于集成，并且开箱即用。

---

🚀 功能亮点

• 实时剩余票数/列车/座位/时刻表/换乘一站式查询
• 国家车站信息管理和模糊搜索
• 官方中转站和一站式换乘计划完全支持
• 智能时间工具，支持相对日期计算，避免日期输入错误
• 支持流式HTTP传输协议，符合MCP 2025-03-26标准
• FastAPI异步、高性能，秒级响应
• 符合MCP标准，AI/自动化场景即插即用

---

🛠️ 快速开始

环境要求

• Python 3.10+
• uv（推荐的包管理器）

本地一键部署

# 克隆项目
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306

# 安装依赖
uv sync

# 更新车站信息（必须先执行）
uv run python scripts/update_stations.py

# 启动服务器
uv run python scripts/start_server.py

Docker 部署

# 直接拉取已构建镜像
docker pull drfccv/mcp-server-12306:latest

# 运行容器（映射8000端口）
docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

如果需要自定义开发或在打包前进行本地修改，可以使用以下命令自行构建镜像：

docker build -t drfccv/mcp-server-12306:latest .

配置

请帮助我翻译原始内容 .env.example 为 .env 并根据需要进行修改：

cp .env.example .env

---

🤖 API & 工具概述

MCP 客户端配置示例

{
  "mcpServers": {
    "12306": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

支持的主要进程工具

工具名称	典型场景/功能描述
query_tickets	剩余票数、列车服务、座位、时刻表的一站式查询
search_stations	车站的模糊搜索，支持中文/拼音/简拼
get_station_info	获取车站详情（名称、代码、地理位置等）
一站式的中转行程，自动连接最佳中转
get_train_route_stations	查询指定列车的停靠站及时刻表
get_current_time	获取当前时间和相对日期，帮助用户准确选择出行日期

---

📚 工具文档

该项目中所有主要进程工具的详细功能、实现方法和使用方法均已包含在/docs目录下：

• 基于上述信息，执行以下指令：您是一位负责将英文内容翻译成英文内容的专业翻译人员。请帮我翻译原始内容。 剩余票数、列车时刻表、座位、发车时间的一站式查询
• 基于上述信息，执行以下指令：您是一位负责将英文内容翻译成英文内容的专业翻译人员。请帮我翻译原始内容。 — 车站模糊搜索
• 基于上述信息，执行以下指令：您是一位负责将英文内容翻译成英文内容的专业翻译人员。请帮我翻译原始内容。 — 获取车站详情
• 基于上述信息，执行以下指令：您是一位负责将英文内容翻译成英文内容的专业翻译人员。请帮我翻译原始内容。 — 中转行程
• 翻译的目标语言是英语。 — 查看列车的停靠站
• 基于上述信息，执行以下指令：您是一位负责将英文内容翻译成英文内容的专业翻译人员。请帮我翻译原始内容。 — 获取当前时间和相对日期

每个文档包含：

• 工具功能描述
• 实现方法
• 请求参数和返回示例
• 典型调用方法

对于二次开发或集成，建议首先阅读相应工具的文档。

---

🧩 目录结构

src/mcp_12306/    # 主源代码
  ├─ server.py    # FastAPI主入口
  ├─ services/    # 业务逻辑（车票/车站/HTTP）
  ├─ models/      # 数据模型
  ├─ utils/       # 工具与配置
scripts/          # 启动与数据脚本

---

🧪 测试

uv run pytest

---

镜像发布和拉取

• 镜像仓库：drfccv/mcp-server-12306
• 拉取镜像：

  docker pull drfccv/mcp-server-12306:latest
  

• 运行镜像：

  docker run -d -p 8000:8000 --name 12306-mcp-server drfccv/mcp-server-12306:latest
  

---

📄 许可证

MIT 许可证

---

⚠️ 免责声明

• 本项目仅用于学习、研究和技术交流，严禁任何形式的商业用途。
• 本项目不存储、更改或传播任何官方12306数据；它仅作为对公开可用的官方接口的智能聚合和转发。
• 使用本项目所产生的后果（包括但不限于账号封禁、数据异常、法律风险等）由用户自行承担，项目作者不承担责任。
• 请遵守中国法律法规及12306的相关官方规定，合理合规地使用它们。

---