tfl-mcp

MCP server for the Transport for London Unified API — lines, journeys, stop points, arrivals, bike points, occupancy, road disruptions and more over stdio.

Installation

npx -y @daanrongen/tfl-mcp

Tools (80 total)

Domain	Tools	Coverage
AccidentStats	accident_stats	Road accidents by year
AirQuality	air_quality	Live pollution forecasts (NO2, O3, PM10, PM2.5, SO2)
BikePoint	bike_points_all, bike_point_search, bike_point_by_id	Santander Cycles availability
Cabwise	cabwise_search	Licensed taxis & minicabs near a location
Journey	journey_plan, journey_modes	Full journey planner (all modes)
Line	14 tools	Status, routes, disruptions, arrivals, timetables, stop sequences
Mode	mode_active_service_types, mode_arrivals	Cross-mode service info
Occupancy	5 tools	Car parks, bike docks, EV charge connectors
Place	7 tools	Search, geo lookup, postcode streets, place types
Road	8 tools	TLRN status, disruptions, closures, roadworks
Search	5 tools	Full-text TfL site/data search
StopPoint	17 tools	Search, arrivals, disruptions, crowding, routes, taxi ranks, car parks
Vehicle	3 tools	ULEZ compliance, emissions surcharge, vehicle arrival tracking

Setup

API key (optional but recommended)

Register for a free key at https://api-portal.tfl.gov.uk/. Without one, requests are rate-limited to ~500/day.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tfl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@daanrongen/tfl-mcp"],
      "env": {
        "TFL_API_KEY": "your-key-here"
      }
    }
  }
}

Or via the CLI:

claude mcp add tfl npx -- -y @daanrongen/tfl-mcp -e TFL_API_KEY=your-key-here

Development

bun install
bun run dev        # run with --watch
bun test           # run test suite
bun run build      # bundle to dist/main.js
bun run inspect    # open MCP Inspector in browser

Inspecting locally

bun run inspect launches the MCP Inspector against the local build:

bun run build && bun run inspect

This opens the Inspector UI in your browser where you can call any tool interactively and inspect request/response shapes.

Journey planner — location IDs

The most common failure mode is passing a free-text name to journey_plan, which causes TfL to return a 300 disambiguation response. The tool handles this gracefully and returns suggested parameterValue IDs to retry with.

Preferred ID formats (most to least reliable):

Format	Example	Notes
ICS code	1000129	Most reliable — use output from stoppoint_search
Naptan ID	940GZZLUVIC	Reliable for tube/rail stations
Postcode	N1C4TB	Always resolves unambiguously
Coordinates	51.5308,-0.1238	Always unambiguous
Free text	King's Cross	May trigger disambiguation

Common station ICS codes:

Station	ICS code
King's Cross St. Pancras	1000129
Victoria	1000248
Waterloo	1000254
London Bridge	1000135
Paddington	1000184
Liverpool Street	1000134
Euston	1000078
Canary Wharf	1001006
Brixton	1000023
Stratford	1000222

Architecture

src/
├── config.ts           # Effect Config — TFL_API_KEY
├── main.ts             # Entry point — ManagedRuntime + StdioServerTransport
├── domain/
│   ├── TflClient.ts    # Context.Tag service interface
│   └── errors.ts       # TflError, TflDisambiguationError
├── infra/
│   ├── TflClientLive.ts  # Layer.effect — HTTP client with disambiguation handling
│   └── TflClientTest.ts  # In-memory test adapter
└── mcp/
    ├── server.ts       # McpServer wired to ManagedRuntime
    ├── utils.ts        # formatSuccess, formatError, formatDisambiguation
    └── tools/          # One module per TfL domain (13 files)