MCP Server 12306

An MCP server that provides 12306 ticket query

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

🚄 MCP Server 12306

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

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

✨ 功能特性

类别	能力
🎫 余票查询	余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤
💰 票价查询	实时查询各车次各席别票价（商务座 → 无座全覆盖）
🏙️ 车站搜索	全国 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 客户端。

安装：

bash

# uvx（推荐，环境隔离）
uvx mcp-server-12306

# 或 pip / pipx
pip install mcp-server-12306

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

config.json

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

其他安装方式（点击展开）

pipx：

config.json

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

本地源码（开发者调试）：

bash

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

config.json

{
  "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 结束会话。

启动：

bash

# 安装后直接启动
mcp-12306

# 或本地源码启动
uv run python scripts/start_server.py

客户端配置：

config.json

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

内置 HTTP 端点：

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

方式三：Docker 部署

bash

# 拉取镜像并运行（默认端口 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`）

bash

# 示例：.env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
LOG_LEVEL=INFO

🏗️ 项目结构

Code

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                   # 依赖锁文件

🧑‍💻 开发指南

bash

# 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 支持！

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Server 12306

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-server-12306": { "command": "npx", "args": ["-y", "mcp-server-12306"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

MCP Server 12306 AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-server-12306?style=directory)](https://allmcps.com/mcp/mcp-server-12306)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-server-12306"><img src="https://allmcps.com/api/badge/mcp-server-12306?style=directory" alt="MCP Server 12306 on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools14/30

Adoption & activity6/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Server 12306 →Install in Claude Desktop Install in Cursor Install in VS Code

MCP Server 12306

An MCP server that provides 12306 ticket query

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

🚄 MCP Server 12306

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

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

📑 目录

✨ 功能特性
🚀 快速开始
🛠️ 工具一览
⚙️ 配置项
🏗️ 项目结构
🧑‍💻 开发指南
📚 详细文档
⚠️ 免责声明
📄 License

✨ 功能特性

类别	能力
🎫 余票查询	余票 / 车次 / 座席 / 时刻一站式查询，支持按车次过滤
💰 票价查询	实时查询各车次各席别票价（商务座 → 无座全覆盖）
🏙️ 车站搜索	全国 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 客户端。

安装：

bash

# uvx（推荐，环境隔离）
uvx mcp-server-12306

# 或 pip / pipx
pip install mcp-server-12306

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

config.json

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

其他安装方式（点击展开）

pipx：

config.json

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

本地源码（开发者调试）：

bash

git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync

config.json

{
  "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 结束会话。

启动：

bash

# 安装后直接启动
mcp-12306

# 或本地源码启动
uv run python scripts/start_server.py

客户端配置：

config.json

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

内置 HTTP 端点：

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

方式三：Docker 部署

bash

# 拉取镜像并运行（默认端口 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`）

bash

# 示例：.env
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
LOG_LEVEL=INFO

🏗️ 项目结构

Code

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                   # 依赖锁文件

🧑‍💻 开发指南

bash

# 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 支持！

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Server 12306

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-server-12306": { "command": "npx", "args": ["-y", "mcp-server-12306"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-server-12306?style=directory)](https://allmcps.com/mcp/mcp-server-12306)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-server-12306"><img src="https://allmcps.com/api/badge/mcp-server-12306?style=directory" alt="MCP Server 12306 on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

40Quality signal: Fair · 40/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools14/30

Adoption & activity6/15

Community engagement0/10

★ Spotlight Slot

Feature Your MCP Server

Get maximum visibility for your server across our directory, search results, and detail pages.

Spotlight Your Server

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Server 12306 →Install in Claude Desktop Install in Cursor Install in VS Code