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 queries for available tickets, stations, stopovers, transfers, and intelligent time tools. It is user-friendly, easy to integrate, and ready to use out of the box.
---
## 🚀 Features
- Real-time one-stop query for available tickets, train schedules, seats, times, and transfers
- Management and fuzzy search of national station information
- Full support for official stopovers and single transfer plans
- Intelligent time tools that support relative date calculations to avoid date input errors
- Streamable HTTP transmission protocol, compliant with MCP 2025-03-26 standard
- FastAPI asynchronous high performance with second-level response times
- 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 package after local modifications, 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 available tickets, train schedules, seats, and times |
| search_stations | Fuzzy search for stations, supporting Chinese/Pinyin/abbreviations |
| get_station_info | Retrieve station details (name, code, geography, etc.) |
| query_transfer | Single transfer plan, automatically stitching together optimal transfers |
| get_train_route_stations | Query specified train stopovers and schedules |
| get_current_time | Get current time and relative dates to help 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 available tickets, train schedules, seats, and times
- [search_stations.md](./docs/search_stations.md) — Fuzzy search for stations
- [get_station_info.md](./docs/get_station_info.md) — Retrieve 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 stopovers
- [get_current_time.md](./docs/get_current_time.md) — Get current time and relative dates
Each document includes:
- Tool function description
- Implementation methods
- Request parameters and return examples
- Typical calling methods
For 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 configurations
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.
---
