What can you do with this server?

The 12306 MCP Server is a high-performance railway ticket inquiry service that interfaces with China's official 12306 railway system via the Model Context Protocol (MCP). * Query Train Tickets (query-tickets): Search real-time train availability between stations for a given date, returning schedules, durations, and seat availability across all seat classes. * Query Ticket Prices (query-ticket-price): Retrieve detailed fare information for trains between two stations, with optional filtering by train number and passenger type (adult/student). * Search Train Stations (search-stations): Intelligently search for stations using Chinese characters, pinyin, abbreviated pinyin, or three-letter station codes — supports fuzzy search. * Query Transfer/Connecting Routes (query-transfer): Find optimal transfer plans between two stations, with options to specify a transfer station, seat preferences, and student tickets. * Get Train Route & Stops (get-train-route-stations): Retrieve the full list of stops for a specific train, including arrival/departure times and dwell times at each station. * Convert Train Code to Official ID (get-train-no-by-train-code): Convert a human-readable train number (e.g., G1) to the official unique internal identifier, typically needed before querying route stops. * Get Current Time (get-current-time): Retrieve the current date/time with timezone support and relative date calculations, useful for assisting with date input. Supports both Stdio mode (for local clients like Claude Desktop) and Streamable HTTP mode (for remote/Docker deployment), implementing the MCP 2025-03-26 standard for seamless AI and automation integration.

Which integrations are available for this server?

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

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.

12306 MCP Server

by drfccv

Overview Schema Related Servers Score Discussions

Python

Remote

🚄 MCP Server 12306

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

PyPI - Version PyPI - Downloads Python - 3.10+ Docker - Pulls License - MIT MCP - SDK v2 Transport - Stdio/HTTP GitHub - Stars

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

📑 目录

Related MCP server: MCP Server

✨ 功能特性

类别	能力
🎫 余票查询	余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤
💰 票价查询	实时查询各车次各席别票价（商务座 → 无座全覆盖）
🏙️ 车站搜索	全国 3382+ 车站，支持中文 / 拼音 / 简拼 / 三字码模糊搜索
🔄 中转换乘	官方换乘方案自动分页抓取，返回完整路径与等待时间
🛤️ 经停查询	查询指定列车全部经停站与到发时刻
🕐 时间工具	获取任意时区当前时间、相对日期计算，辅助选择出行日期
🔌 双传输模式	Stdio（本地）\| Streamable HTTP（远程），同一核心实例共享
🔄 协议自动协商	基于 MCP SDK v2，自动兼容握手时代（2025-11-25）与现代协议（2026-07-28）

🚀 快速开始

环境要求

依赖	要求
Python	`>= 3.10, < 3.14`
包管理器	`uv`（推荐）或 `pip` / `pipx`
网络	可访问 12306 官方接口

💡 推荐使用 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 端点：

端点	方法	说明
`/mcp`	POST / GET / DELETE	MCP Streamable HTTP 协议入口
`/health`	GET	健康检查（含已加载车站数、活跃会话数）
`/schema/tools`	GET	全部工具 JSON Schema
`/`	GET	服务信息（版本、协议版本、端点）

方式三：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

🛠️ 工具一览

工具名	功能	必填参数
`query-tickets`	余票 / 车次 / 座席 / 时刻一站式查询	`from_station`、`to_station`、`train_date`
`query-ticket-price`	实时查询车次票价	`from_station`、`to_station`、`train_date`
`search-stations`	车站模糊搜索（中文 / 拼音 / 简拼 / 三字码）	`query`
`query-transfer`	中转换乘方案查询	`from_station`、`to_station`、`train_date`
`get-train-route-stations`	查询列车经停站及时刻表	`train_no`、`from_station`、`to_station`、`train_date`
`get-train-no-by-train-code`	车次号 → 官方唯一编号	`train_code`、`from_station`、`to_station`、`train_date`
`get-current-time`	当前时间与相对日期（辅助选日期）	无

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

⚙️ 配置项

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

环境变量	默认值	说明
`SERVER_HOST`	`0.0.0.0`	HTTP 监听地址
`SERVER_PORT`	`8000`	HTTP 监听端口
`DEBUG`	`false`	调试模式
`LOG_LEVEL`	`INFO`	日志级别（`DEBUG` / `INFO` / `WARNING` / `ERROR`）

# 示例：.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 会话保持），业务错误与网络错误分离处理。

📚 详细文档

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

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

⚠️ 免责声明

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

📄 License

MIT © Drfccv

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

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

5dResponse time

–Release cycle

–Releases (12mo)

Commit activity

Issues opened vs closed

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

MyAIServ MCP Server
RAG Systems Vector Databases
eagurin
A
license
Not graded
quality
D
maintenance
A high-performance FastAPI server supporting Model Context Protocol (MCP) for seamless integration with Large Language Models, featuring REST, GraphQL, and WebSocket APIs, along with real-time monitoring and vector search capabilities.
Updated a year ago (2025-03-14 21:51 UTC)
8
MIT
MCP Server
Developer Tools Code Execution Autonomous Agents
freedanfan
A
license
Not graded
quality
D
maintenance
A FastAPI-based implementation of the Model Context Protocol that enables standardized interaction between AI models and development environments, making it easier for developers to integrate and manage AI tasks.
Updated a year ago (2025-05-02 00:24 UTC)
10
MIT
Caltrain MCP Server
Travel & Transportation Agent Orchestration
davidyen1124
F
license
A
quality
A
maintenance
A Model Context Protocol server that provides real-time Caltrain schedule information, allowing AI assistants to look up train departures between any stations and access station information using GTFS data.
Updated a month ago (2026-07-16 17:14 UTC)
2
10
12306-MCP
Search Travel & Transportation
freestylefly
A
license
A
quality
D
maintenance
A Model Context Protocol server that allows large language models to search for and analyze Chinese railway (12306) tickets through a simple API interface.
Updated a year ago (2025-05-28 10:02 UTC)
8
9,847
19
MIT

View all related MCP servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloud
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
TravelMind MCP
TravelMind: 8 MCP tools for travel (12306 trains, flights, hotels, geocode, planning, policy).
mcp
A Model Context Protocol server for Wix AI tools

View all MCP Connectors

Appeared in Searches

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/drfccv/mcp-server-12306'

If you have feedback or need assistance with the MCP directory API, please join our Discord server