mcp-server-12306

Name: mcp-server-12306
Author: drfccv

bydrfccv· 1 MCP server

Stars

354

Forks

How to install mcp-server-12306?

drfccv/mcp-server-12306

$git clone https://github.com/drfccv/mcp-server-12306

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Install & use

Install mcp-server-12306 by running `git clone https://github.com/drfccv/mcp-server-12306`, then use it for the current task and follow its documentation at https://github.com/drfccv/mcp-server-12306.

Files · 1

View on GitHub

README.md

1	# 🚄 MCP Server 12306
2
3	![screenshot](https://img.shields.io/badge/12306-MCP-blue?logo=railway)
4	![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python)
5	![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
6
7	---
8
9	## ✨ 项目简介
10
11	MCP Server 12306 是一款基于 Model Context Protocol (MCP) 的高性能火车票查询服务，支持官方 12306 余票、票价、车站、经停、换乘查询以及智能时间工具，适配 AI/自动化/智能助手等场景，开箱即用。
12
13
14	---
15
16	## 🚀 功能亮点
17
18	- 实时余票/车次/座席/时刻/换乘一站式查询
19	- 全国车站信息管理与模糊搜索，支持中文、拼音、简拼、三字码
20	- 官方经停站、中转换乘方案全支持
21	- 实时查询各车次票价信息
22	- 智能时间工具，支持时区和时间戳
23	- 双传输模式：Stdio（Claude Desktop 推荐）\| Streamable HTTP（远程部署）
24	- MCP 2025-03-26 标准，AI/自动化场景即插即用
25
26	---
27
28	## 🛠️ 快速上手
29
30	本项目支持两种运行模式：
31	1. Stdio 模式：适用于 Claude Desktop 等本地 MCP 客户端（推荐）。
32	2. Streamable HTTP 模式：适用于远程部署或通过 SSE/POST 访问。
33
34	---
35
36	### 模式 1：Stdio 模式（Claude Desktop 推荐）
37
38	在此模式下，MCP Server 通过标准输入/输出与客户端通信，无需占用网络端口。
39
40	#### 方式 A：使用 uvx（推荐）
41
42	`uvx` 是 `uv` 包管理器提供的工具，环境隔离且启动极快。
43
44	```json
45	{
46	"mcpServers": {
47	"12306": {
48	"command": "uvx",
49	"args": ["mcp-server-12306"]
50	}
51	}
52	}
53	```
54
55	#### 方式 B：使用 pipx
56
57	如果您更习惯使用 pipx：
58
59	```json
60	{
61	"mcpServers": {
62	"12306": {
63	"command": "pipx",
64	"args": ["run", "--no-cache", "mcp-server-12306"]
65	}
66	}
67	}
68	```
69
70	#### 方式 C：本地源码运行
71
72	适用于开发者调试：
73
74	```bash
75	cd mcp-server-12306
76	uv sync
77	```
78
79	```json
80	{
81	"mcpServers": {
82	"12306": {
83	"command": "uv",
84	"args": ["--directory", "/path/to/mcp-server-12306", "run", "mcp-server-12306"]
85	}
86	}
87	}
88	```
89
90
91	---
92
93	### 模式 2：Streamable HTTP 模式
94
95	在此模式下，Server 启动一个 Web 服务（默认 8000 端口），支持 MCP 的 SSE 和 POST 交互。
96
97	#### 方式 A：pip 安装后运行
98
99	```bash
100	# 安装 HTTP 模式（含 FastAPI / uvicorn）
101	pip install mcp-server-12306[http]
102	# 启动
103	mcp-12306
104	```
105
106	#### 方式 B：本地源码运行
107
108	```bash
109	# 1. 克隆并安装依赖
110	git clone https://github.com/drfccv/mcp-server-12306.git
111	cd mcp-server-12306
112	uv sync --extra http
113
114	# 2. 启动服务器
115	uv run python scripts/start_server.py
116	```
117
118	MCP 客户端配置：
119
120	```json
121	{
122	"mcpServers": {
123	"12306": {
124	"url": "http://localhost:8000/mcp"
125	}
126	}
127	}
128	```
129
130	#### 方式 C：Docker 部署
131
132	```bash
133	# 拉取镜像并运行
134	docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest
135	```
136
137	---
138
139	## 🤖 工具一览
140
141	### 支持的主流程工具
142	\| 工具名 \| 功能描述 \|
143	\|-----------------------------\|-----------------------------------\|
144	\| `query-tickets` \| 余票/车次/座席/时刻一站式查询 \|
145	\| `query-ticket-price` \| 实时查询各车次票价信息 \|
146	\| `search-stations` \| 车站模糊搜索，支持中文/拼音/简拼 \|
147	\| `query-transfer` \| 中转换乘方案，自动拼接最优路径 \|
148	\| `get-train-route-stations` \| 查询指定列车经停站及时刻表 \|
149	\| `get-train-no-by-train-code`\| 车次号转官方唯一编号 \|
150	\| `get-current-time` \| 当前时间与相对日期，辅助日期选择 \|
151
152	---
153
154	## 📚 工具文档
155
156	本项目所有主流程工具的详细功能、实现与使用方法，均已收录于 [`/docs`](./docs) 目录下：
157
158	- [query_tickets.md](./docs/query_tickets.md) — 余票/车次/座席/时刻一站式查询
159	- [query_ticket_price.md](./docs/query_ticket_price.md) — 实时查询各车次票价信息
160	- [search_stations.md](./docs/search_stations.md) — 车站智能搜索
161	- [query_transfer.md](./docs/query_transfer.md) — 中转换乘方案
162	- [get_train_route_stations.md](./docs/get_train_route_stations.md) — 查询列车经停站
163	- [get_current_time.md](./docs/get_current_time.md) — 获取当前时间与相对日期
164
165	每个文档包含：
166	- 工具功能说明
167	- 实现方法
168	- 请求参数与返回示例
169	- 典型调用方式
170
171	如需二次开发或集成，建议先阅读对应工具的文档。
172
173	---
174
175	## 🧩 目录结构
176
177	```
178	src/mcp_12306/ # 主源代码
179	├─ http_server.py # FastAPI HTTP 传输层
180	├─ stdio_server.py # Stdio 传输层 + CLI 入口
181	├─ services/ # 业务逻辑
182	│ ├─ station_service.py # 车站数据服务
183	│ └─ ticket_service.py # 票务查询核心（stdio/HTTP 共享）
184	├─ utils/ # 配置与日期工具
185	│ ├─ config.py
186	│ └─ date_utils.py
187	└─ resources/ # 静态资源（车站数据）
188	scripts/ # 启动与数据更新脚本
189	├─ start_server.py # HTTP 模式一键启动
190	└─ update_stations.py # 更新车站数据
191	```
192
193	---
194
195	## 📄 License
196	MIT License
197
198	---
199
200	## ⚠️ 免责声明
201
202	- 本项目仅供学习、研究与技术交流，严禁用于任何商业用途。
203	- 本项目不存储、不篡改、不传播任何 12306 官方数据，仅作为官方公开接口的智能聚合与转发。
204	- 使用本项目造成的任何后果（包括但不限于账号封禁、数据异常、法律风险等）均由使用者本人承担，项目作者不承担任何责任。
205	- 请遵守中国法律法规及 12306 官方相关规定，合理合规使用。
206
207	---

6 picks

Type

Install mcp-server-12306 by running `git clone https://github.com/drfccv/mcp-server-12306`, then use it for the current task and follow its documentation at https://github.com/drfccv/mcp-server-12306.

mcp-server-12306

How to install mcp-server-12306?

Related

mcp-server-12306

How to install mcp-server-12306?

Related