MCP Server 12306

🚄 MCP Server 12306

基于 Model Context Protocol (MCP) 的 12306 火车票查询服务

支持 余票 / 票价 / 车站 / 经停 / 换乘 / 时间 六大查询能力，开箱即用，适配 AI 助手、自动化脚本、智能终端等场景。

---

📑 目录

• ✨ 功能特性
• 🚀 快速开始
• 环境要求
• 方式一：Stdio 模式（本地客户端推荐）
• 方式二：Streamable HTTP 模式（远程部署）
• 方式三：Docker 部署
• 🛠️ 工具一览
• ⚙️ 配置项
• 🏗️ 项目结构
• 🧑💻 开发指南
• 📚 详细文档
• ⚠️ 免责声明
• 📄 License

---

✨ 功能特性

---

🚀 快速开始

环境要求

💡 推荐使用 uv：环境隔离、安装快、锁文件管理依赖版本。

方式一：Stdio 模式（本地客户端推荐）

MCP Server 通过标准输入/输出与客户端通信，不占用网络端口，适合 Claude Desktop、Cursor 等本地 MCP 客户端。

安装：

# uvx（推荐，环境隔离）

uvx mcp-server-12306

或 pip / pipx

pip install mcp-server-12306

客户端配置（如 claude_desktop_config.json）：

{

"mcpServers": { "12306": { "command": "uvx", "args": ["mcp-server-12306"] } } }

其他安装方式（点击展开）

pipx：

{

"mcpServers": { "12306": { "command": "pipx", "args": ["run", "--no-cache", "mcp-server-12306"] } } }

本地源码（开发者调试）：

git clone https://github.com/drfccv/mcp-server-12306.git

cd mcp-server-12306 uv sync

{

"mcpServers": { "12306": { "command": "uv", "args": ["--directory", "/path/to/mcp-server-12306", "run", "mcp-server-12306"] } } }

方式二：Streamable HTTP 模式（远程部署）

Server 启动 Web 服务（默认 8000 端口），通过 MCP Streamable HTTP 协议通信：POST 发送 JSON-RPC、GET 订阅流式响应、DELETE 结束会话。

启动：

# 安装后直接启动

mcp-12306

或本地源码启动

uv run python scripts/start_server.py

客户端配置：

{

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

内置 HTTP 端点：

方式三：Docker 部署

# 拉取镜像并运行（默认端口 8000）

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

自定义端口

docker run -d -p 8080:8000 \ -e SERVER_HOST=0.0.0.0 \ -e SERVER_PORT=8000 \ --name mcp-server-12306 \ drfccv/mcp-server-12306:latest

---

🛠️ 工具一览

📖 每个工具的参数说明、返回示例、调用示例详见 📚 详细文档。

---

⚙️ 配置项

通过环境变量或项目根目录 .env 文件配置：

# 示例：.env

SERVER_HOST=127.0.0.1 SERVER_PORT=8000 LOG_LEVEL=INFO

---

🏗️ 项目结构

mcp-server-12306/

├── src/mcp_12306/ # 主包 │ ├── server.py # 核心 Server（工具注册与分发，双传输共享） │ ├── stdio_server.py # Stdio 传输层 + CLI 入口 │ ├── http_server.py # Streamable HTTP 传输层 + HTTP 端点 │ ├── services/ # 业务逻辑 │ │ ├── station_service.py # 车站数据服务（加载/搜索/编码转换） │ │ └── ticket_service.py # 票务查询核心（7 个工具实现） │ ├── utils/ # 配置与日期工具 │ │ ├── config.py # pydantic-settings 配置 │ │ └── date_utils.py # 日期校验工具 │ └── resources/ # 静态资源（车站数据 station_name.js） ├── scripts/ # 运维脚本 │ ├── start_server.py # HTTP 模式一键启动（环境自检） │ └── update_stations.py # 更新车站数据 ├── docs/ # 工具详细文档 ├── pyproject.toml # 项目元数据 / 依赖 / 构建配置 ├── Dockerfile # 多阶段构建（python:3.12-alpine） ├── server.json # MCP 注册表元数据 └── uv.lock # 依赖锁文件

---

🧑💻 开发指南

# 1. 克隆并初始化

git clone https://github.com/drfccv/mcp-server-12306.git cd mcp-server-12306 uv sync

2. 类型检查（mypy，严格模式）

uv run mypy src scripts

3. 代码格式化

uv run black src scripts uv run isort src scripts

4. 构建与发布

uv run python -m build uv run twine upload dist/*

架构要点：

• server.py 是传输无关的核心模块——工具注册（TOOL_HANDLERS）与业务分发（call_tool）都在此，stdio 与 HTTP 复用同一实例，保证两种模式行为完全一致。
• 工具 Schema 单一来源于 ticket_service.MCP_TOOLS，HTTP 的 /schema/tools 端点与 MCP 工具列表同源。
• 网络请求统一走 _request_with_retry（自动重试 + init 会话保持），业务错误与网络错误分离处理。

---

📚 详细文档

每份文档均包含：功能说明、实现方法、请求参数、返回示例与典型调用方式。

---

⚠️ 免责声明

• 本项目仅供学习、研究与技术交流，严禁用于任何商业用途。
• 本项目仅作为官方公开接口的智能聚合与转发。
• 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
• 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。

---

📄 License

MIT © Drfccv

---

⭐ 如果这个项目对你有帮助，欢迎 Star 支持！