Content
# 🚄 12306 MCP Server
  
---
## ✨ Project Introduction
12306 MCP Server is a high-performance train ticket query backend based on Model Context Protocol (MCP), supporting official 12306 ticket availability, station, stopover, transfer queries, and intelligent time tools, suitable for AI/automation/intelligent assistant scenarios. It features a user-friendly interface, easy integration, and is ready to use out of the box.
---
## 🚀 Feature Highlights
- Real-time ticket availability/train/seat/schedule/transfer one-stop query
- National station information management and fuzzy search
- Full support for official stopover stations and single transfer plans
- Intelligent time tools that support relative date calculations to avoid date input errors
- Streamable HTTP transmission protocol, supporting MCP 2025-03-26 standard
- FastAPI asynchronous high performance with second-level response
- MCP standard, plug-and-play for AI/automation scenarios
---
## 🛠️ Quick Start
### Environment Requirements
- Python 3.10+
- [uv](https://astral.sh/uv/) (recommended package manager)
### Local One-Click Deployment
```bash
# Clone the project
git clone https://github.com/drfccv/mcp-server-12306.git
cd mcp-server-12306
# Install dependencies
uv sync
# Update station information (must be executed first)
uv run python scripts/update_stations.py
# Start the server
uv run python scripts/start_server.py
```
### Docker Deployment
```bash
# Pull the pre-built image directly
docker pull drfccv/mcp-server-12306:latest
# Run the container (mapping port 8000)
docker run -d -p 8000:8000 --name mcp-server-12306 drfccv/mcp-server-12306:latest
```
> If you need to customize development or modify locally before packaging, you can build the image yourself with the following command:
> ```bash
> docker build -t drfccv/mcp-server-12306:latest .
> ```
### Configuration
Copy `.env.example` to `.env` and modify as needed:
```bash
cp .env.example .env
```
---
## 🤖 API & Tool Overview
### MCP Client Configuration Example
```json
{
"mcpServers": {
"12306": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### Supported Main Process Tools
| Tool Name | Typical Scenario/Function Description |
|--------------------------|--------------------------------------------|
| query_tickets | One-stop query for ticket availability/train/seat/schedule |
| search_stations | Fuzzy search for stations, supporting Chinese/Pinyin/abbreviations |
| get_station_info | Get station details (name, code, geography, etc.) |
| query_transfer | Single transfer plan, automatically stitching the optimal transfer |
| get_train_route_stations | Query specified train stopover stations and timetable |
| get_current_time | Get current time and relative date, helping users accurately select travel dates |
---
## 📚 Tool Documentation
Detailed functions, implementations, and usage methods for all main process tools in this project are documented in the [`/docs`](./docs) directory:
- [query_tickets.md](./docs/query_tickets.md) — One-stop query for ticket availability/train/seat/schedule
- [search_stations.md](./docs/search_stations.md) — Fuzzy search for stations
- [get_station_info.md](./docs/get_station_info.md) — Get station details
- [query_transfer.md](./docs/query_transfer.md) — Single transfer plan
- [get_train_route_stations.md](./docs/get_train_route_stations.md) — Query train stopover 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
If you need secondary development or integration, it is recommended to read the corresponding tool documentation first.
---
## 🧩 Directory Structure
```
src/mcp_12306/ # Main source code
├─ server.py # FastAPI main entry
├─ services/ # Business logic (tickets/stations/HTTP)
├─ models/ # Data models
├─ utils/ # Utilities and configuration
scripts/ # Startup and data scripts
```
---
## 🧪 Testing
```bash
uv run pytest
```
---
## 📦 Image Release and Pull
- Image Repository: [drfccv/mcp-server-12306](https://hub.docker.com/r/drfccv/mcp-server-12306)
- Pull the image:
```bash
docker pull drfccv/mcp-server-12306:latest
```
- Run the image:
```bash
docker run -d -p 8000:8000 --name 12306-mcp-server drfccv/mcp-server-12306:latest
```
---
## 📄 License
MIT License
---
## ⚠️ Disclaimer
- This project is for learning, research, and technical communication purposes only, and is strictly prohibited for any commercial use.
- This project does not store, alter, or disseminate any official 12306 data, serving only as an intelligent aggregation and forwarding of the official public interface.
- Any consequences arising from the use of this project (including but not limited to account bans, data anomalies, legal risks, etc.) are the sole responsibility of the user, and the project author bears no responsibility.
- Please comply with Chinese laws and regulations and the relevant provisions of 12306, and use it reasonably and legally.
---
