Content
# 🚄 MCP Server 12306
---
## ✨ Project Introduction
MCP Server 12306 is a high-performance train ticket query backend based on Model Context Protocol (MCP), supporting official 12306 remaining tickets, fares, stations, stops, transfer queries, and intelligent time tools, adapted to AI/automation/intelligent assistant scenarios. It is user-friendly, easy to integrate, and ready to use out of the box.
---
## 🚀 Key Features
- Real-time remaining tickets/trains/seats/schedules/transfers one-stop query
- National station information management and fuzzy search
- Official stop stations, one-time transfer schemes fully supported
- Real-time query of fare information for each train
- Intelligent time tools, supporting time zones and timestamps
- Streamable HTTP/STDIO transmission protocol, supporting MCP 2025-03-26 standard
- FastAPI asynchronous high performance, second-level response
- MCP standard, plug-and-play for AI/automation scenarios
---
## 🛠️ Quick Start
This project supports two running modes:
1. **Stdio Mode**: Suitable for local MCP clients such as Claude Desktop (recommended).
2. **Streamable HTTP Mode**: Suitable for remote deployment or access via SSE/Post.
---
### Mode 1: Stdio Mode (Recommended for Claude Desktop)
In this mode, MCP Server communicates with the client through standard input/output without occupying network ports.
#### Method A: Use uvx (Recommended)
`uvx` is a tool provided by the `uv` package manager, with environment isolation and extremely fast startup.
```json
{
"mcpServers": {
"12306": {
"command": "uvx",
"args": ["mcp-server-12306"]
}
}
}
```
#### Method B: Use pipx
If you are more accustomed to using pipx:
```json
{
"mcpServers": {
"12306": {
"command": "pipx",
"args": ["run", "--no-cache", "mcp-server-12306"]
}
}
}
```
#### Method C: Local Source Code Execution
Suitable for developer debugging:
```json
{
"mcpServers": {
"12306": {
"command": "uv",
"args": ["run", "python", "-m", "mcp_12306.cli"],
"cwd": "/path/to/mcp-server-12306"
}
}
}
```
---
### Mode 2: Streamable HTTP Mode
In this mode, the Server starts a Web service (default port 8000), supporting MCP's SSE (Server-Sent Events) and POST interaction.
#### Method A: Local Source Code Execution
```bash
# 1. Clone and install dependencies
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
uv sync
# 2. Start the server
uv run python scripts/start_server.py
```
**MCP Client Configuration:**
```json
{
"mcpServers": {
"12306": {
"url": "http://localhost:8000/mcp"
}
}
}
```
#### Method B: Docker Deployment
```bash
# Pull the image and run
docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest
```
---
## 🤖 Tool List
### Supported Main Process Tools
| Tool Name | Typical Scenario/Function Description |
|--------------------------|----------------------------------|
| query_tickets | One-stop query for remaining tickets/trains/seats/schedules |
| query_ticket_price | Real-time query of fare information for each train |
| search_stations | Fuzzy station search, supports Chinese/Pinyin/Abbreviations |
| get_station_info | Get station details (name, code, geography, etc.) |
| query_transfer | One-time transfer scheme, automatically splicing the optimal transfer |
| get_train_route_stations | Query the stop stations and timetable of the specified train |
| get_current_time | Get the current time and relative date to help users accurately select travel dates |
---
## 📚 Tool Documentation
Detailed functions, implementations, and usage methods of all main process tools in this project are included in the [`/docs`](./docs) directory:
- [query_tickets.md](./docs/query_tickets.md) — One-stop query for remaining tickets/trains/seats/schedules
- [query_ticket_price.md](./docs/query_ticket_price.md) — Real-time query of fare information for each train
- [search_stations.md](./docs/search_stations.md) — Intelligent station search
- [query_transfer.md](./docs/query_transfer.md) — One-time transfer scheme
- [get_train_route_stations.md](./docs/get_train_route_stations.md) — Query train stop stations
- [get_current_time.md](./docs/get_current_time.md) — Get the current time and relative date
Each document contains:
- Tool function description
- Implementation method
- Request parameters and return examples
- Typical calling methods
If you need secondary development or integration, it is recommended to read the documentation of the corresponding tool first.
---
## 🧩 Directory Structure
```
src/mcp_12306/ # Main source code
├─ server.py # FastAPI main entry
├─ services/ # Business logic (tickets/stations/HTTP)
├─ utils/ # Tools and configuration
scripts/ # Startup and data scripts
```
---
## 📄 License
MIT License
---
## ⚠️ Disclaimer
- This project is for learning, research, and technical exchange only, and is strictly prohibited for any commercial use.
- This project does not store, tamper with, or disseminate any 12306 official data, and only serves as an intelligent aggregation and forwarding of official public interfaces.
- The user shall bear any consequences (including but not limited to account bans, data anomalies, legal risks, etc.) caused by the use of this project, and the project author shall not be liable for any responsibility.
- Please abide by Chinese laws and regulations and 12306 official regulations, and use them reasonably and compliantly.
