{
"markdown": "\n\n# 🚄 MCP Server 12306\n\n**基于 Model Context Protocol (MCP) 的 12306 火车票查询服务**\n\n[](https://pypi.org/project/mcp-server-12306)\n[](https://pypi.org/project/mcp-server-12306)\n[](https://pypi.org/project/mcp-server-12306)\n[](https://hub.docker.com/r/drfccv/mcp-server-12306)\n[](https://github.com/drfccv/mcp-server-12306/blob/main/LICENSE)\n[](https://github.com/modelcontextprotocol/python-sdk)\n[](docs/)\n[](https://github.com/drfccv/mcp-server-12306)\n\n
\n\n支持 **余票 / 票价 / 车站 / 经停 / 换乘 / 时间** 六大查询能力，开箱即用，适配 AI 助手、自动化脚本、智能终端等场景。\n\n
\n\n---\n\n## 📑 目录\n\n- [✨ 功能特性](#-功能特性)\n- [🚀 快速开始](#-快速开始)\n - [环境要求](#环境要求)\n - [方式一：Stdio 模式（本地客户端推荐）](#方式一stdio-模式本地客户端推荐)\n - [方式二：Streamable HTTP 模式（远程部署）](#方式二streamable-http-模式远程部署)\n - [方式三：Docker 部署](#方式三docker-部署)\n- [🛠️ 工具一览](#️-工具一览)\n- [⚙️ 配置项](#️-配置项)\n- [🏗️ 项目结构](#️-项目结构)\n- [🧑💻 开发指南](#-开发指南)\n- [📚 详细文档](#-详细文档)\n- [⚠️ 免责声明](#️-免责声明)\n- [📄 License](#-license)\n\n---\n\n## ✨ 功能特性\n\n| 类别 | 能力 |\n|------|------|\n| 🎫 **余票查询** | 余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤 |\n| 💰 **票价查询** | 实时查询各车次各席别票价（商务座 → 无座全覆盖） |\n| 🏙️ **车站搜索** | 全国 3382+ 车站，支持中文 / 拼音 / 简拼 / 三字码模糊搜索 |\n| 🔄 **中转换乘** | 官方换乘方案自动分页抓取，返回完整路径与等待时间 |\n| 🛤️ **经停查询** | 查询指定列车全部经停站与到发时刻 |\n| 🕐 **时间工具** | 获取任意时区当前时间、相对日期计算，辅助选择出行日期 |\n| 🔌 **双传输模式** | Stdio（本地）\\| Streamable HTTP（远程），同一核心实例共享 |\n| 🔄 **协议自动协商** | 基于 MCP SDK v2，自动兼容握手时代（2025-11-25）与现代协议（2026-07-28） |\n\n---\n\n## 🚀 快速开始\n\n### 环境要求\n\n| 依赖 | 要求 |\n|------|------|\n| Python | `>= 3.10, < 3.14` |\n| 包管理器 | `uv`（推荐）或 `pip` / `pipx` |\n| 网络 | 可访问 12306 官方接口 |\n\n> 💡 推荐使用 [`uv`](https://docs.astral.sh/uv/)：环境隔离、安装快、锁文件管理依赖版本。\n\n### 方式一：Stdio 模式（本地客户端推荐）\n\n> MCP Server 通过标准输入/输出与客户端通信，**不占用网络端口**，适合 Claude Desktop、Cursor 等本地 MCP 客户端。\n\n**安装：**\n\n```bash\n# uvx（推荐，环境隔离）\nuvx mcp-server-12306\n\n# 或 pip / pipx\npip install mcp-server-12306\n```\n\n**客户端配置**（如 `claude_desktop_config.json`）：\n\n```json\n{\n \"mcpServers\": {\n \"12306\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-server-12306\"]\n }\n }\n}\n```\n\n\n其他安装方式（点击展开）
\n\n**pipx：**\n\n```json\n{\n \"mcpServers\": {\n \"12306\": {\n \"command\": \"pipx\",\n \"args\": [\"run\", \"--no-cache\", \"mcp-server-12306\"]\n }\n }\n}\n```\n\n**本地源码（开发者调试）：**\n\n```bash\ngit clone https://github.com/drfccv/mcp-server-12306.git\ncd mcp-server-12306\nuv sync\n```\n\n```json\n{\n \"mcpServers\": {\n \"12306\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/mcp-server-12306\", \"run\", \"mcp-server-12306\"]\n }\n }\n}\n```\n\n \n\n### 方式二：Streamable HTTP 模式（远程部署）\n\n> Server 启动 Web 服务（默认 `8000` 端口），通过 MCP Streamable HTTP 协议通信：`POST` 发送 JSON-RPC、`GET` 订阅流式响应、`DELETE` 结束会话。\n\n**启动：**\n\n```bash\n# 安装后直接启动\nmcp-12306\n\n# 或本地源码启动\nuv run python scripts/start_server.py\n```\n\n**客户端配置：**\n\n```json\n{\n \"mcpServers\": {\n \"12306\": {\n \"url\": \"http://localhost:8000/mcp\"\n }\n }\n}\n```\n\n**内置 HTTP 端点：**\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/mcp` | POST / GET / DELETE | MCP Streamable HTTP 协议入口 |\n| `/health` | GET | 健康检查（含已加载车站数、活跃会话数） |\n| `/schema/tools` | GET | 全部工具 JSON Schema |\n| `/` | GET | 服务信息（版本、协议版本、端点） |\n\n### 方式三：Docker 部署\n\n```bash\n# 拉取镜像并运行（默认端口 8000）\ndocker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest\n\n# 自定义端口\ndocker run -d -p 8080:8000 \\\n -e SERVER_HOST=0.0.0.0 \\\n -e SERVER_PORT=8000 \\\n --name mcp-server-12306 \\\n drfccv/mcp-server-12306:latest\n```\n\n---\n\n## 🛠️ 工具一览\n\n| 工具名 | 功能 | 必填参数 |\n|--------|------|----------|\n| `query-tickets` | 余票 / 车次 / 座席 / 时刻一站式查询 | `from_station`、`to_station`、`train_date` |\n| `query-ticket-price` | 实时查询车次票价 | `from_station`、`to_station`、`train_date` |\n| `search-stations` | 车站模糊搜索（中文 / 拼音 / 简拼 / 三字码） | `query` |\n| `query-transfer` | 中转换乘方案查询 | `from_station`、`to_station`、`train_date` |\n| `get-train-route-stations` | 查询列车经停站及时刻表 | `train_no`、`from_station`、`to_station`、`train_date` |\n| `get-train-no-by-train-code` | 车次号 → 官方唯一编号 | `train_code`、`from_station`、`to_station`、`train_date` |\n| `get-current-time` | 当前时间与相对日期（辅助选日期） | 无 |\n\n> 📖 每个工具的**参数说明、返回示例、调用示例**详见 [📚 详细文档](#-详细文档)。\n\n---\n\n## ⚙️ 配置项\n\n通过环境变量或项目根目录 `.env` 文件配置：\n\n| 环境变量 | 默认值 | 说明 |\n|----------|--------|------|\n| `SERVER_HOST` | `0.0.0.0` | HTTP 监听地址 |\n| `SERVER_PORT` | `8000` | HTTP 监听端口 |\n| `DEBUG` | `false` | 调试模式 |\n| `LOG_LEVEL` | `INFO` | 日志级别（`DEBUG` / `INFO` / `WARNING` / `ERROR`） |\n\n```bash\n# 示例：.env\nSERVER_HOST=127.0.0.1\nSERVER_PORT=8000\nLOG_LEVEL=INFO\n```\n\n---\n\n## 🏗️ 项目结构\n\n```\nmcp-server-12306/\n├── src/mcp_12306/ # 主包\n│ ├── server.py # 核心 Server（工具注册与分发，双传输共享）\n│ ├── stdio_server.py # Stdio 传输层 + CLI 入口\n│ ├── http_server.py # Streamable HTTP 传输层 + HTTP 端点\n│ ├── services/ # 业务逻辑\n│ │ ├── station_service.py # 车站数据服务（加载/搜索/编码转换）\n│ │ └── ticket_service.py # 票务查询核心（7 个工具实现）\n│ ├── utils/ # 配置与日期工具\n│ │ ├── config.py # pydantic-settings 配置\n│ │ └── date_utils.py # 日期校验工具\n│ └── resources/ # 静态资源（车站数据 station_name.js）\n├── scripts/ # 运维脚本\n│ ├── start_server.py # HTTP 模式一键启动（环境自检）\n│ └── update_stations.py # 更新车站数据\n├── docs/ # 工具详细文档\n├── pyproject.toml # 项目元数据 / 依赖 / 构建配置\n├── Dockerfile # 多阶段构建（python:3.12-alpine）\n├── server.json # MCP 注册表元数据\n└── uv.lock # 依赖锁文件\n```\n\n---\n\n## 🧑💻 开发指南\n\n```bash\n# 1. 克隆并初始化\ngit clone https://github.com/drfccv/mcp-server-12306.git\ncd mcp-server-12306\nuv sync\n\n# 2. 类型检查（mypy，严格模式）\nuv run mypy src scripts\n\n# 3. 代码格式化\nuv run black src scripts\nuv run isort src scripts\n\n# 4. 构建与发布\nuv run python -m build\nuv run twine upload dist/*\n```\n\n**架构要点：**\n\n- `server.py` 是**传输无关的核心模块**——工具注册（`TOOL_HANDLERS`）与业务分发（`call_tool`）都在此，stdio 与 HTTP 复用同一实例，保证两种模式行为完全一致。\n- 工具 Schema **单一来源**于 `ticket_service.MCP_TOOLS`，HTTP 的 `/schema/tools` 端点与 MCP 工具列表同源。\n- 网络请求统一走 `_request_with_retry`（自动重试 + init 会话保持），业务错误与网络错误分离处理。\n\n---\n\n## 📚 详细文档\n\n| 文档 | 内容 |\n|------|------|\n| [query_tickets.md](./docs/query_tickets.md) | 余票 / 车次 / 座席 / 时刻一站式查询 |\n| [query_ticket_price.md](./docs/query_ticket_price.md) | 实时票价查询 |\n| [search_stations.md](./docs/search_stations.md) | 车站智能搜索 |\n| [query_transfer.md](./docs/query_transfer.md) | 中转换乘方案 |\n| [get_train_route_stations.md](./docs/get_train_route_stations.md) | 列车经停站查询 |\n| [get_current_time.md](./docs/get_current_time.md) | 当前时间与相对日期 |\n\n每份文档均包含：功能说明、实现方法、请求参数、返回示例与典型调用方式。\n\n---\n\n## ⚠️ 免责声明\n\n- 本项目仅供学习、研究与技术交流，**严禁用于任何商业用途**。\n- 本项目不存储、不篡改、不传播任何 12306 官方数据，仅作为官方公开接口的智能聚合与转发。\n- 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。\n- 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。\n\n---\n\n## 📄 License\n\n[MIT](./LICENSE) © [Drfccv](https://github.com/drfccv)\n\n---\n\n\n\n**⭐ 如果这个项目对你有帮助，欢迎 Star 支持！**\n\n
\n\n\n",
"bytes": 7903,
"sha": "77aecb98a3c1fbf66c832daa98716724454dce8aac74e5ff694cdcc9a42e50cc",
"repo_slug": "drfccv/mcp-server-12306",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_drfccv_mcp_server_12306_07370c98/readme"
}