MCP Server

Active

MIT

io.github.drfccv/mcp-server-12306 MCP Server

io.github.drfccv/mcp-server-12306

Real-time Chinese railway ticket query via 12306 API integrated with MCP for AI assistants

What is the io.github.drfccv/mcp-server-12306 MCP server?

MCP Server 12306 is a high-performance Model Context Protocol server that provides real-time access to China's 12306 railway ticket system. It enables AI assistants to query ticket availability, prices, train routes, stations, and transfer options with support for both Stdio and HTTP streaming protocols.

This server integrates with China's official 12306 railway booking system to offer comprehensive ticket query capabilities. It supports real-time ticket availability, pricing, station information, train routes, and transfer planning—useful for travel planning automation, AI assistants helping users book tickets, and railway information aggregation.

How to install io.github.drfccv/mcp-server-12306

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

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

Cursor

~/.cursor/mcp.json

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

Windsurf

~/.codeium/windsurf/mcp_config.json

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

VS Code

.vscode/mcp.json

{
  "servers": {
    "mcp-server-12306": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-server-12306"
      ]
    }
  }
}

Claude Code

claude mcp add mcp-server-12306 -- uvx mcp-server-12306

Tools & capabilities

Tools this server exposes to the agent.

query_tickets — Query real-time ticket availability, train numbers, seat types, schedules, and timetables in one request
query_ticket_price — Fetch real-time ticket pricing information for specific train routes
search_stations — Intelligent station search supporting Chinese characters, pinyin, and abbreviations
get_station_info — Retrieve detailed station information including name, code, and geographic details
query_transfer — Find optimal one-stop transfer/connection plans between stations
get_train_route_stations — Query all stops and timetable for a specific train
get_current_time — Get current time with timezone support and relative date helpers for accurate travel date selection

Use cases

Query available train tickets between two cities for a specific date and seat preference
Check real-time ticket prices across different train options to find the cheapest fares
Search for railway stations by name or abbreviation to get station codes and details
Plan multi-leg journeys by finding optimal transfer points between stations
Retrieve complete train schedules and all stops for a specific train number
Build travel planning chatbots that help users find and book railway tickets

io.github.drfccv/mcp-server-12306 MCP server FAQ

What is MCP Server 12306?

It's an MCP server that provides real-time access to China's 12306 railway ticket system, allowing AI assistants to query tickets, prices, stations, and transfer options.

Is this server free to use?

Yes, the server itself is free and open-source (MIT License). It queries 12306's official public API, though actual ticket booking would require a 12306 account.

How do I install it in Claude Desktop?

Add to your Claude Desktop config using Stdio mode with uvx: {"12306": {"command": "uvx", "args": ["mcp-server-12306"]}} or use pipx/local source alternatives.

Does it require authentication?

The server queries 12306's public API endpoints for ticket information. Actual ticket booking would require 12306 account credentials, but basic queries do not.

What are the deployment options?

Supports Stdio mode (Claude Desktop, local clients) and Streamable HTTP mode (remote deployment via FastAPI on port 8000, with Docker support).

Is this an official 12306 service?

No, this is an unofficial third-party MCP wrapper around 12306's public API. It's for learning and research only; commercial use is prohibited per the license.

README (reference)

Source of truth, from the repository.

🚄 MCP Server 12306

✨ 项目简介

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

🚀 功能亮点

实时余票/车次/座席/时刻/换乘一站式查询
全国车站信息管理与模糊搜索
官方经停站、一次中转方案全支持
实时查询各车次票价信息
智能时间工具，支持时区和时间戳
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 官方相关规定，合理合规使用。

View repository →