uk-rail-mcp

MCP server for live UK rail data, using the free-for-personal-use Realtime Trains next-generation API, with pre-filled thetrainline.com booking links. Trainline itself has no public API, so this wraps open rail data and hands off to Trainline for purchase.

Tools

• search_stations — name/CRS lookup (2,608 GB stations bundled)

• live_departures — live board for a station, optionally filtered to a destination; includes a Trainline booking link when filtered

• live_arrivals — live arrivals board

• service_details — full calling pattern + real-time info for one train

• trainline_booking_link — pre-filled thetrainline.com search URL

Setup

1. Sign in at https://api-portal.rtt.io (needs an RTT unified login account) and request an API token. The portal issues either a long-life access token or a refresh token — it will tell you which.

2. Build:

npm install
npm run build

Run as a remote server (default) — for claude.ai custom connectors

RTT_ACCESS_TOKEN=... MCP_PATH_TOKEN=some-long-random-string npm start
# or, if the portal gave you a refresh token:
RTT_REFRESH_TOKEN=... MCP_PATH_TOKEN=some-long-random-string npm start

Serves Streamable HTTP MCP at POST /mcp/<MCP_PATH_TOKEN> (or /mcp if no token is set), plus GET /healthz. Stateless mode: no sessions, safe behind load balancers.

Claude connects from Anthropic's cloud, not your machine, so the server must be publicly reachable — deploy to Railway, Fly.io, Render, or any VPS (all read PORT automatically). Then in claude.ai: Settings → Connectors → Add custom connector, and paste https://your-host/mcp/<token>.

The path token is lightweight access control (this server has no OAuth): anyone with the full URL can burn your RTT quota, so use a long random token and treat the URL as a secret. For anything beyond personal use, put proper OAuth in front (the MCP SDK supports it).

Run locally in Claude Desktop instead

node dist/index.js --stdio

claude_desktop_config.json:

{
  "mcpServers": {
    "uk-rail": {
      "command": "node",
      "args": ["/absolute/path/to/trainline-mcp/dist/index.js", "--stdio"],
      "env": {
        "RTT_ACCESS_TOKEN": "your-token-from-api-portal.rtt.io"
      }
    }
  }
}

Things to verify (unofficial/undocumented behaviour)

• The client targets the RTT next-generation API (base https://data.rtt.io, bearer auth) and was written directly against the official OpenAPI spec (https://realtimetrains.github.io/api-specification/). Field parsing should be sanity-checked against one real response once you have a token.

• RTT forbids putting tokens in distributable client apps; this server-side proxy pattern is exactly what they require, but keep the token out of the repo.

• The Trainline deep-link format (/book/results?origin=...&destination=...) is not officially documented and may change — test one link in a browser.

Limitations / roadmap

• UK (GB) only — RTT has no European coverage.

• No fares or journey planning with pricing; that data is licence-gated (National Rail OJP / Rail Data Marketplace, or a Trainline Partner Solutions agreement).

• No booking — deliberate; handled by the Trainline handoff link.