Mcp Server 12306

📑 目录

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

✨ 功能特性

🚀 快速开始

环境要求

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

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

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

安装：

# uvx（推荐，环境隔离）uvx mcp-server-12306
# 或 pip / pipxpip install mcp-server-12306

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

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

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

git clone https://github.com/drfccv/mcp-server-12306.gitcd mcp-server-12306uv 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 文件配置：

# 示例：.envSERVER_HOST=127.0.0.1SERVER_PORT=8000LOG_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.gitcd mcp-server-12306uv sync
# 2. 类型检查（mypy，严格模式）uv run mypy src scripts
# 3. 代码格式化uv run black src scriptsuv run isort src scripts
# 4. 构建与发布uv run python -m builduv 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 官方数据，仅作为官方公开接口的智能聚合与转发。
• 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
• 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。

📄 License

MIT © Drfccv