uktrains

An agent-first UK train journey CLI and stdio MCP server. It's built for a personal LLM agent to search journeys, compare fares, and hand the human a pre-filled booking link — the tool never takes payment and never claims a booking was made. Fulfilment means one thing: a correct, pre-filled retailer checkout link the human taps to pay.

JSON is the default output everywhere (CLI and MCP alike); pass --pretty on the CLI for a human-readable table.

What it does today

• Resolves UK station names/aliases to CRS codes, including group stations ("Manchester", "London").

• Builds a journey intent from --from/--to plus --depart-after or --arrive-by (and the return-leg equivalents), and produces pre-filled booking links (National Rail Enquiries journey planner, plus Trainline where a verified station mapping exists).

• At Tier 1, fetches BR Fares flow-level fares (railcard-aware) and ranks options by cheapest/fastest/balanced, including return-vs-two-singles comparison.

• doctor reports which tier is active and validates configured keys.

• setup walks an agent (or a human) through the two optional signups.

live (CLI) and live_status (MCP) exist as structured stubs today — they return a TIER_UNAVAILABLE error with a setup pointer rather than pretending to have live data. Live departures/delays and richer in-tool journey planning land in a later plan (Tier 2).

Related MCP server: hafasmcp

Capability tiers

No free API combines journey planning with fares, and Darwin live data requires a Rail Data Marketplace account with human approval — so the tool degrades gracefully instead of demanding setup upfront.

Run uktrains doctor at any time to see the active tier and exactly what's missing to reach the next one.

Install

For agents

If you are an LLM agent: read AGENTS.md — it is written for you and covers install, MCP registration, setup shepherding, and how to present options to your human.

git clone https://github.com/aaryan-gulia/uktrains.git
cd uktrains
npm install
npm run build

The built CLI is at dist/cli/index.js and runnable directly:

node dist/cli/index.js search --from KGX --to YRK --depart-after 2026-08-01T09:00:00+01:00

Or invoke it via npx once linked/published, or point an MCP client at the built entry point (below) — no global install required.

For humans

Same steps, then optionally npm link (or install globally once published) so the uktrains command is on PATH.

Requires Node.js 20+.

MCP client config

If uktrains is on PATH (e.g. via npm link):

{
  "command": "uktrains",
  "args": ["mcp"]
}

From a source checkout, without installing globally:

{
  "command": "node",
  "args": ["/absolute/path/to/uktrains/dist/cli/index.js", "mcp"]
}

The server exposes four tools: search_journeys, get_booking_link, live_status (Tier 2 stub), and lookup_station. Tool descriptions are normative — they tell the calling agent, for example, that arriveBy is a station arrival time and that the agent is responsible for adding transit and buffer time to the actual appointment.

CLI examples

# Search a journey (JSON by default; --pretty for a human-readable table)
uktrains search --from KGX --to YRK --depart-after 2026-08-01T09:00:00+01:00 --pretty

# Same, but restrict fares to a railcard and rank by cheapest
uktrains search --from "London" --to "Manchester" \
  --depart-after 2026-08-01T09:00:00+01:00 \
  --railcard 16-25 --rank-by cheapest

# Booking links only, no fare lookup
uktrains link --from KGX --to YRK --depart-after 2026-08-01T09:00:00+01:00

# Resolve a station name or CRS code
uktrains stations york

# Agent-drivable setup: machine-readable next steps for both signups
uktrains setup --json

# Store a key once the human has completed a signup
uktrains setup --set brfares=<key>

# Check active tier and validate configured keys
uktrains doctor

All time flags (--depart-after, --arrive-by, --return-depart-after, --return-arrive-by) take ISO-8601 timestamps and require an explicit timezone offset (e.g. 2026-08-01T09:00:00+01:00 or Z). Offset-less times are rejected with a structured INVALID_INPUT error — silently guessing a timezone produces silently wrong booking links.

Setup walkthrough

uktrains setup --json (the default) prints machine-readable steps so an agent can shepherd the human through both signups in the background, while Tier 0 already delivers working booking links:

1. BR Fares (Tier 1) — open https://www.brfares.com/api/login.html, register a free non-commercial account, obtain an API key, then run uktrains setup --set brfares=<key>.

2. Rail Data Marketplace (Tier 2, live data — not yet consumed by this build) — open https://raildata.org.uk, create an individual account (approval typically takes 1–3 working days), subscribe to the free "LDBWS – Public" product, then run uktrains setup --set rdm=<key>.

Config is stored at ~/.config/uktrains/config.json and holds only rail-domain state: API keys, railcards, and ranking preferences. No home station, no calendar integration — the calling agent already knows that.

Attribution and licensing notes

• Output carries "Powered by National Rail Enquiries" per NRE's OGL terms.

• Each user brings their own API keys. RDM and BR Fares agreements are per-account — this tool never shares keys or redistributes upstream data.

• The BR Fares free tier is registered for non-commercial use only.

• Fares are flow-level (origin→destination, railcard-adjusted), not per-train, and are stamped indicative and time-stamped at quote time. Advance fares are additionally flagged subject to availability, since Advance quota lives in the closed National Reservation Service that no open source exposes. Re-search before presenting a fare older than ~15 minutes.

• The tool never takes payment and never states or implies that a booking was completed — only that a booking link was produced.

Further reading

• Design spec: docs/superpowers/specs/2026-07-31-uktrains-design.md

• Implementation plan: docs/superpowers/plans/2026-07-31-uktrains-core-tier0-1.md

• Agent guide: AGENTS.md