MCP Server 12306

How to use

You can use MCP Server 12306 with an MCP client in two primary ways: a local, stdin/stdout communication mode for tight integration with desktop clients, and a streamable HTTP mode for remote access via HTTP or server-sent events. In local mode, you interact through standard input and output without opening network ports. In HTTP mode, you run a web service (default port 8000) and communicate using an MCP-compatible URL.

For local stdin/stdout usage, you can run the server through different runtime packaging options. Choose the option that fits your environment and tooling preference. The following configurations demonstrate how to wire the MCP server into your client by using a dedicated command and arguments.

How to install

Prerequisites: you need Python installed for the FastAPI-based server, and you should have a compatible MCP client. You may also want a container or a helper runtime to manage the local server process.

Choose a mode and follow the corresponding setup steps. Below are concrete, copy-paste-ready instructions for each supported mode.

Note: If you prefer to run locally without network exposure, use the Stdio mode. If you plan to deploy remotely or want web access, use the Streamable HTTP mode.

Additional sections

Configuration for Stdio mode is provided in code examples. For a local, non-networked setup, you can select one of the following commands depending on your preferred tool. The MCP client configuration must point to the chosen runtime so the client can connect through stdin/stdout.

{
  "mcpServers": {
    "12306": {
      "command": "uvx",
      "args": ["mcp-server-12306"]
    }
  }
}

{
  "mcpServers": {
    "12306": {
      "command": "pipx",
      "args": ["run", "--no-cache", "mcp-server-12306"]
    }
  }
}

{
  "mcpServers": {
    "12306": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_12306.cli"],
      "cwd": "/path/to/mcp-server-12306"
    }
  }
}

Streamable HTTP mode setup

In this mode, start a web service (default port 8000) that supports MCP SSE and POST interactions. Use the provided runtime commands to launch the server and configure the MCP client to point to the HTTP URL.

# 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

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

Docker deployment

You can run the HTTP MCP server in a Docker container for easy deployment and scaling.

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

Notes

The server exposes tools for querying real-time ticket availability, prices, station details, transfers, and current time. Use the MCP client to send queries and receive structured results suitable for AI assistants and automation workflows.

query_tickets

One-shot query for real-time ticket availability, trains, seats, and times across routes.

query_ticket_price

Real-time retrieval of ticket prices for trains and segments.

search_stations

Station search with support for Chinese names, pinyin, and abbreviations.

get_station_info

Fetch station details including name, code, and geography.

query_transfer

Compute a single-transfer itinerary with an optimized transfer plan.

get_train_route_stations

Query a train's stops and timetable for specified trains.

get_current_time

Obtain the current time and relative dates to help users select travel dates.