Server facts
12306 MCP
Project
- Author
- Joooook
- Repository
- github.com/Joooook/12306-mcp
- License
- MIT
- Category
- Maps & Travel
Tech
- Runtime / language
- nodeTypeScript
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 2,391
- Last commit
- Data as of
Tags
- 12306
- Rail Travel
- Station Lookup
- Train Tickets
- Typescript
Overview
12306 MCP exposes railway ticket-search functions to MCP-compatible language models. Its documented features include searching ticket information, filtering train results, checking stops, and finding transfer options. The supplied tool inventory adds station-name and station-code resolution so an assistant can turn a user's Chinese city or station name into the identifiers required by later searches. Separate lookups return all stations in a city, a representative city code, or detailed station information from a telecode. A date tool uses the Shanghai timezone to help interpret relative travel dates before a ticket query is submitted.
Direct ticket availability and interline availability are distinct operations. The transfer-query description notes that only the first ten results are currently supported. For a specified train and interval, another tool returns calling stations together with arrival, departure, and dwell information. This makes the project useful for comparing services and understanding an itinerary, but the provided interface is about searching rather than a documented booking or payment workflow. The README identifies the project as intended for learning and lists additional interfaces as future work. Users can launch the TypeScript server with npx over standard input/output, choose an HTTP port, or build a Docker image for either mode. The example MCP client configuration does not specify credentials or environment variables.
Install & configure
Requirements
- Node.js and npx
- An MCP-compatible client
npx -y 12306-mcpUses the README's CLI-stdio example. HTTP operation is documented with a --port argument, and Docker build/run examples cover both modes. No required environment variables or minimum Node.js version are stated.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"12306-mcp": {
"command": "npx",
"args": [
"-y",
"12306-mcp"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"12306-mcp": {
"command": "npx",
"args": [
"-y",
"12306-mcp"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"12306-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"12306-mcp"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"12306-mcp": {
"command": "npx",
"args": [
"-y",
"12306-mcp"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"12306-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"12306-mcp"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository tool metadata. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| get-current-date | Return the current Shanghai-time date for resolving relative travel dates. |
| get-stations-code-in-city | List all train stations and their codes for a Chinese city name. |
| get-station-code-of-citys | Resolve Chinese city names to representative station codes. |
| get-station-code-by-names | Resolve specific Chinese station names into station names and codes. |
| get-station-by-telecode | Retrieve station details such as name, pinyin, and city from a telecode. |
| get-tickets | Query remaining ticket availability through 12306. |
| get-interline-tickets | Query transfer-ticket availability, currently limited to the first ten results. |
| get-train-route-stations | Inspect a train's stops, arrival and departure times, and dwell durations within an interval. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Find direct train-ticket availability for a travel request.
- Compare available transfer itineraries.
- Resolve Chinese city and station names into station codes.
- Inspect a train's intermediate stops and timetable details.
Strengths
- Combines ticket searches with station-code resolution.
- Supports direct and transfer queries.
- Includes timezone-aware date resolution and detailed stop queries.
Limitations
- The transfer query is limited to the first ten results.
- Booking and payment operations are not documented.
- The README frames the project as a learning tool.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
