home / mcp / 12306 mcp server

12306 MCP Server

This is a 12306 ticket search server based on the Model Context Protocol (MCP).

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "joooook-12306-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "12306-mcp"
      ]
    }
  }
}

You run an MCP server that exposes a simple API to search and filter 12306 train tickets using the Model Context Protocol. It lets you perform station passes, transfers, and related queries through lightweight MCP clients, enabling seamless integration with large language models and other tooling.

How to use

Use an MCP client to connect to the 12306 MCP Server and perform ticket searches. You can run the server locally, then query for available trains, apply filters, check interchanges, and request transfer routes. The server is designed to be easy to invoke from your MCP-enabled tooling, returning structured results you can present or post-process.

How to install

Prerequisites: Node.js and npm installed on your machine.

Clone the project and install dependencies.

git clone https://github.com/Joooook/12306-mcp.git
cd 12306-mcp
npm i

Configuration and usage notes

You can run the server in several ways, including a quick CLI invocation, a ported HTTP mode, or via Docker. The documented options below show the exact commands to start the server in stdio mode and how you can configure MCP clients to connect.

MCP server configuration for stdio (local) execution is shown here. This config uses npx to run the MCP server directly.

{
  "mcpServers": {
    "12306_mcp": {
      "command": "npx",
      "args": [
        "-y",
        "12306-mcp"
      ]
    }
  }
}

Available tools

search_tickets

Query 12306 ticket information with optional filters (date, origin, destination, seat type) and return matching results.

filter_trains

Apply train-level filters such as duration, number of transfers, and filtering by stopovers to narrow results.

transfer_query

Query possible transfer routes between origin and destination, including layover details.