Setup guide · Updated 2026-09-03 · source revision d4ac43f

Set up China Rail MCP

A beginner-friendly path from choosing a client to proving that a real railway query works. You do not need a 12306 account or programming experience.

No 12306 login required. This server only reads public journey-planning data and never books tickets.

Three terms in plain language

MCP: A standard that lets an AI client call tools supplied by another program.
stdio: A local connection: the desktop client starts the MCP program on the same computer.
remote MCP: A hosted HTTPS connection used by cloud clients and, when supported, phone apps.

Choose the procedure you need

Use on this computerOn this computerChoose local stdio. Your AI client starts China Rail MCP on the same computer.Use on a phoneOn a phone or across devicesChoose a private remote deployment. Your AI client connects to China Rail MCP over HTTPS.

New to the command line? Let an AI set it up

Choose local stdio. Your AI client starts China Rail MCP on the same computer.

Best for: The easiest and safest first setup. No public server, domain, or secret is required.

What you need

A desktop MCP client that supports local stdio
Git
Node.js 20 or later
npm 10 or later

Possible cost

China Rail MCP itself is free. Your AI client or model provider may charge separately.

What will happen

Choose a desktop client that supports local stdio. Qwen Code, TRAE, and Claude Desktop are common routes; check the client guide before installing anything.
Copy the AI setup request below into a coding AI that can use your terminal and files.
Allow it to install missing software, restart an app, or change settings only after it explains the action.
Do not accept “the build passed” as completion. Ask for a real get_provider_status call and a real train search from the configured client.

Copy this entire request into a coding AI

The AI should perform the setup and prove the result, not stop after giving you a tutorial.

Install and configure China Rail MCP on this computer until I can make a real Chinese railway query from the AI client I currently use. Repository: https://github.com/TakeruF/china-rail-mcp

Perform the work instead of only giving me a tutorial. First identify the operating system, AI/MCP client, and whether Git, Node.js, and npm are available. If the target client is unclear, ask only that question. Read the latest README and self-hosting guide. Explain and ask before installing software, using administrator access, restarting a GUI app, or changing security settings.

Clone the repository into a stable location without overwriting existing work. Run npm ci and npm run verify. Find the absolute paths to Node.js and dist/index.js, then add a local stdio server named china-rail using the configuration format actually supported by my client. Preserve all existing settings. Local mode needs no .env, 12306 account, cookie, or secret; never ask me for them.

Reload the client as required. Prove the setup from the configured client by calling get_provider_status, searching for 上海虹桥 with search_stations, and then searching for trains from 上海虹桥 to 杭州东 on a date inside the current sales window. Distinguish a working local connection from a temporary 12306 live-query failure. Finish by reporting the installation path, client configuration changed, verification result, actual MCP tool result, and one example question I can ask next. Do not commit or push repository changes.

Prefer to do it yourself?

Run these commands in a terminal. Then add the absolute dist/index.js path to your client's stdio MCP configuration.

git clone https://github.com/TakeruF/china-rail-mcp.git
cd china-rail-mcp
npm ci
npm run verify

Do not call it complete until

npm run verify passes
The client lists China Rail MCP or its six tools
get_provider_status returns through the client
A current station or train query returns through the client

If something looks wrong

A silent npm start is normal: an stdio server waits for the client over standard input/output.
If the client cannot find Node.js, use the absolute path returned by command -v node.
If only the live query fails, the MCP connection may still be correct; check provider status and the current 12306 availability separately.

Open the implementation README for exact project details

Want to use it from a phone? Let an AI host a private server

Choose a private remote deployment. Your AI client connects to China Rail MCP over HTTPS.

Best for: Phone access or multiple devices. This route has more account, hosting, authentication, and possible cost requirements.

What you need

GitHub and Vercel accounts
An AI client account that supports custom remote MCP
A stable HTTPS deployment
Private authentication and OAuth

Possible cost

China Rail MCP is free, but hosting, model usage, or the required client plan may cost money.

What will happen

Check the client compatibility guide first. Consumer chat apps do not all accept arbitrary custom MCP servers.
Copy the remote setup request below into a coding AI that can use both a browser and terminal.
Approve account sign-in, cloud project creation, charges, and Production deployment only after their impact is explained.
Verify deployment, account connection, and the phone tool call as three separate results.

Copy this entire request into a coding AI

The AI should perform the setup and prove the result, not stop after giving you a tutorial.

Deploy China Rail MCP as a private personal remote service and continue until I can make a real Chinese railway query from my phone's AI client. Repository: https://github.com/TakeruF/china-rail-mcp

Perform the work instead of only giving me a tutorial. Read the latest README, self-hosting guide, and the current client's official remote-MCP documentation. Confirm that my GitHub, Vercel, and AI client accounts have the required features. Explain and ask before charges, cloud project creation, account sign-in, or Production deployment.

Clone the repository safely, run npm ci and npm run verify, and do not modify or push its source. Create a personal Vercel project. Generate a strong unique MCP_HTTP_BEARER_TOKEN and store it only as a masked Production environment variable. Never show it in source, .env, Git, chat, screenshots, logs, or the final report.

Deploy the current main commit to Production and use its stable HTTPS hostname. Run npm run smoke:http -- https://ACTUAL_HOST/api. Confirm health and OAuth metadata return 200, and that unauthenticated /api/mcp returns the expected 401 with discovery information. This 401 proves authentication is active.

Connect https://ACTUAL_HOST/api/mcp using the flow actually supported by my current client and complete OAuth. First call get_provider_status and search_stations on web or desktop. Then open a new conversation on the phone with the same account, enable the connection, and search for trains from 上海虹桥 to 杭州东 on a date inside the sales window. Report deployment success, account connection success, and mobile tool-call success separately. Never make the server public or remove authentication as a workaround. Finish by reporting only the project name, HTTPS MCP URL without secrets, deployment and tool-call results, possible cost points, and how to revoke access.

What the hosted setup must produce

The implementation repository contains the exact deployment and OAuth details. These are the milestones to check.

npm ci
npm run verify
npm run smoke:http -- https://YOUR_HOST/api
Connect https://YOUR_HOST/api/mcp in the supported AI client

Do not call it complete until

The Production deployment and unauthenticated smoke test pass
OAuth completes and a web or desktop client can call a tool
The same account can see the connection on the phone
A real tool call succeeds from a new phone conversation

If something looks wrong

An unauthenticated 401 from /api/mcp is expected when discovery information is present.
A successful deployment does not prove that the account or phone app supports custom MCP.
If mobile access is missing, check the client version, account plan, region, staged rollout, and workspace policy. Do not disable authentication.

Open the implementation README for exact project details

Keep these boundaries

China Rail MCP is read-only. It does not log in, book, purchase, solve CAPTCHAs, or bypass restrictions.
Local mode never needs a 12306 account, user cookie, API key, or .env file.
Keep remote deployments private. Never paste the bearer secret into chat or publish it in a repository.
Verify important travel information in an official 12306 channel because public upstream formats and availability can change.

Check whether your AI client supports it

Plans, regions, and supported connection types change. Check the dated compatibility table before paying or deploying.

Open the MCP client table