Content
# MCP Server 12306
---
## Project Introduction
MCP Server 12306 is a high-performance train ticket query backend based on the Model Context Protocol (MCP), supporting official 12306 ticket availability, prices, stations, stops, and transfer queries, as well as intelligent time tools, suitable for AI/automation/intelligent assistant scenarios. The interface is friendly, easy to integrate, and ready to use.
---
## Key Features
- Real-time ticket availability/carriage/seats/schedules/transfer one-stop query
- National station information management and fuzzy search
- Official stop stations and one-time transfer solutions fully supported
- Real-time query of ticket prices for each train
- Intelligent time tool, 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, AI/automation scenarios plug-and-play
---
## Quick Start
This project supports two operating modes:
1. **Stdio Mode**: Suitable for local MCP clients like Claude Desktop (recommended).
2. **Streamable HTTP Mode**: Suitable for remote deployment or access through 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 a network port.
#### Method A: Using uvx (Recommended)
`uvx` is a tool provided by the `uv` package manager, with environment isolation and fast startup.
```json
{
"mcpServers": {
"12306": {
"command": "uvx",
"args": ["mcp-server-12306"]
}
}
}
```
#### Method B: Using pipx
If you prefer using pipx:
```json
{
"mcpServers": {
"12306": {
"command": "pipx",
"args": ["run", "--no-cache", "mcp-server-12306"]
}
}
}
```
#### Method C: Running Local Source Code
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: Running Local Source Code
```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 | Ticket availability/train/seats/schedules one-stop query |
| query_ticket_price | Real-time query of ticket prices for each train |
| search_stations | Station fuzzy search, supporting Chinese/pinyin/short spell |
| get_station_info | Get station details (name, code, geography, etc.) |
| query_transfer | One-time transfer solution, automatic splicing optimal transfer |
| get_train_route_stations | Query specified train stop stations and schedules |
| get_current_time | Get current time and relative date, helping users accurately choose travel dates |
---
## Tool Documentation
The detailed functions, implementation, and usage methods of all main process tools in this project are documented in the [`/docs`](./docs) directory:
- [query_tickets.md](./docs/query_tickets.md) — Ticket availability/train/seats/schedules one-stop query
- [query_ticket_price.md](./docs/query_ticket_price.md) — Real-time query of ticket prices for each train
- [search_stations.md](./docs/search_stations.md) — Intelligent station search
- [query_transfer.md](./docs/query_transfer.md) — One-time transfer solution
- [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 current time and relative date
Each document includes:
- Tool function description
- Implementation method
- Request parameters and return examples
- Typical calling methods
For secondary development or integration, it is recommended to read the corresponding tool documentation.
---
## 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 only for learning, research, and technical exchange, and is strictly prohibited for any commercial use.
- This project does not store, modify, or disseminate any official 12306 data, and only serves as an intelligent aggregation and forwarding of official open interfaces.
- Any consequences caused by using this project (including but not limited to account blocking, data anomalies, legal risks, etc.) shall be borne by the user, and the project author shall not bear any responsibility.
- Please comply with Chinese laws and regulations and 12306 official regulations, and use reasonably and legally.
---
