MCP Server 12306

🚀 12306 MCP Server

12306 MCP Server is a high - performance backend for train ticket queries based on the Model Context Protocol (MCP). It supports official 12306 queries for remaining tickets, stations, stopovers, transfers, and intelligent time tools, making it suitable for scenarios such as AI, automation, and smart assistants. It features a user - friendly interface, is easy to integrate, and ready to use out of the box.

✨ Features

• One - stop query for real - time remaining tickets, train numbers, seats, schedules, and transfers.
• Management and fuzzy search of national station information.
• Full support for official stopover stations and single - transfer solutions.
• Intelligent time tools that support relative date calculations to avoid date input errors.
• Streamable HTTP transport protocol, supporting the MCP 2025 - 03 - 26 standard.
• High - performance asynchronous FastAPI with second - level response.
• MCP standard, plug - and - play for AI/automation scenarios.

🚀 Quick Start

Environment Requirements

• Python 3.10+
• uv (Recommended package manager)

Local One - Click Deployment

# 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

# Pull the pre - built image directly
docker pull drfccv/mcp-server-12306:latest

# Run the container (map 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:

docker build -t drfccv/mcp-server-12306:latest .

Configuration

Copy .env.example to .env and modify it as needed:

cp .env.example .env

💻 Usage Examples

MCP Client Configuration Example

{
  "mcpServers": {
    "12306": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Supported Main - Process Tools

📚 Documentation

Detailed functions, implementations, and usage methods of all main - process tools in this project are included in the directory:

• query_tickets.md — One - stop query for remaining tickets, train numbers, seats, and schedules
• search_stations.md — Fuzzy search for stations
• get_station_info.md — Get station details
• query_transfer.md — Single - transfer solutions
• get_train_route_stations.md — Query train stopover stations
• get_current_time.md — Get the current time and relative dates

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 documentation of the corresponding tool first.

🔧 Technical Details

Directory Structure

src/mcp_12306/    # Main source code
  ├─ server.py    # FastAPI main entry
  ├─ services/    # Business logic (tickets/stations/HTTP)
  ├─ models/      # Data models
  ├─ utils/       # Tools and configurations
scripts/          # Startup and data scripts

Testing

uv run pytest

📦 Installation

Image Release and Pull

• Image repository: drfccv/mcp-server-12306
• Pull the image:

  docker pull drfccv/mcp-server-12306:latest
  

• Run the image:

  docker run -d -p 8000:8000 --name 12306-mcp-server drfccv/mcp-server-12306:latest
  

📄 License

This project is under the MIT License.

⚠️ Important Note

• This project is for learning, research, and technical exchange only. Commercial use is strictly prohibited.
• This project does not store, modify, or spread any official 12306 data. It only serves as an intelligent aggregator and forwarder of official public interfaces.
• Users shall bear all consequences (including but not limited to account bans, data anomalies, legal risks, etc.) caused by using this project. The project author shall not assume any responsibility.
• Please comply with Chinese laws and regulations and relevant official 12306 regulations, and use the project reasonably and legally.