How do I use 12306 MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@12306 MCP Server check tickets from Beijing to Shanghai for tomorrow" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Provides containerized deployment of the 12306 MCP Server with pre-built images available on Docker Hub, allowing for isolated and portable execution across different environments

Supports configuration through environment variables using .env files, allowing customization of server settings

Implements an async high-performance API server using FastAPI, enabling real-time train ticket queries with SSE streaming protocol support

Supports installation via Git repository cloning, enabling access to the latest code and version control features

Hosts the source code repository, enabling collaboration, issue tracking and access to the codebase

Includes testing infrastructure for verifying functionality of the 12306 train ticket querying components

🚄 MCP Server 12306

screenshot FastAPI License: MIT

✨ 项目简介

MCP Server 12306是一款基于 Model Context Protocol (MCP) 的高性能火车票查询后端，支持官方 12306 余票、票价、车站、经停、换乘查询以及智能时间工具，适配 AI/自动化/智能助手等场景。界面友好，易于集成，开箱即用。

Related MCP server: Pulse CN MCP Server

🚀 功能亮点

实时余票/车次/座席/时刻/换乘一站式查询
全国车站信息管理与模糊搜索
官方经停站、一次中转方案全支持
实时查询各车次票价信息
智能时间工具，支持时区和时间戳
Streamable HTTP/STDIO传输协议，支持MCP 2025-03-26标准
FastAPI异步高性能，秒级响应
MCP标准，AI/自动化场景即插即用

🛠️ 快速上手

本项目支持两种运行模式：

Stdio 模式：适用于 Claude Desktop 等本地 MCP 客户端（推荐）。
Streamable HTTP 模式：适用于远程部署或通过 SSE/Post 访问。

模式 1：Stdio 模式（Claude Desktop 推荐）

在此模式下，MCP Server 通过标准输入/输出与客户端通信，无需占用网络端口。

方式 A：使用 uvx（推荐）

uvx 是 uv 包管理器提供的工具，环境隔离且启动极快。

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

方式 B：使用 pipx

如果您更习惯使用 pipx：

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

方式 C：本地源码运行

适用于开发者调试：

{ "mcpServers": { "12306": { "command": "uv", "args": ["run", "python", "-m", "mcp_12306.cli"], "cwd": "/path/to/mcp-server-12306" } } }

模式 2：Streamable HTTP 模式

在此模式下，Server 启动一个 Web 服务（默认 8000 端口），支持 MCP 的 SSE（Server-Sent Events）和 POST 交互。

方式 A：本地源码运行

# 1. 克隆并安装依赖 git clone https://github.com/drfccv/mcp-server-12306.git cd mcp-server-12306 uv sync # 2. 启动服务器 uv run python scripts/start_server.py

MCP 客户端配置：

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

方式 B：Docker 部署

# 拉取镜像并运行 docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest

🤖 工具一览

支持的主流程工具

工具名	典型场景/功能描述
query_tickets	余票/车次/座席/时刻一站式查询
query_ticket_price	实时查询各车次票价信息
search_stations	车站模糊搜索，支持中文/拼音/简拼
get_station_info	获取车站详情（名称、代码、地理等）
query_transfer	一次中转换乘方案，自动拼接最优中转
get_train_route_stations	查询指定列车经停站及时刻表
get_current_time	获取当前时间与相对日期，帮助用户准确选择出行日期

📚 工具文档

本项目所有主流程工具的详细功能、实现与使用方法，均已收录于 /docs 目录下：

query_tickets.md — 余票/车次/座席/时刻一站式查询
query_ticket_price.md — 实时查询各车次票价信息
search_stations.md — 车站智能搜索
query_transfer.md — 一次中转换乘方案
get_train_route_stations.md — 查询列车经停站
get_current_time.md — 获取当前时间与相对日期

每个文档包含：

工具功能说明
实现方法
请求参数与返回示例
典型调用方式

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

🧩 目录结构

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

📄 License

MIT License

⚠️ 免责声明

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

12306 MCP Server