TfL

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

GitHub

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

bunx @daanrongen/tfl-mcp

Tools (80 total)

DomainToolsCoverage
AccidentStatsaccident_statsRoad accidents by year
AirQualityair_qualityLive pollution forecasts (NO2, O3, PM10, PM2.5, SO2)
BikePointbike_points_all, bike_point_search, bike_point_by_idSantander Cycles availability
Cabwisecabwise_searchLicensed taxis & minicabs near a location
Journeyjourney_plan, journey_modesFull journey planner (all modes)
Line14 toolsStatus, routes, disruptions, arrivals, timetables, stop sequences
Modemode_active_service_types, mode_arrivalsCross-mode service info
Occupancy5 toolsCar parks, bike docks, EV charge connectors
Place7 toolsSearch, geo lookup, postcode streets, place types
Road8 toolsTLRN status, disruptions, closures, roadworks
Search5 toolsFull-text TfL site/data search
StopPoint17 toolsSearch, arrivals, disruptions, crowding, routes, taxi ranks, car parks
Vehicle3 toolsULEZ compliance, emissions surcharge, vehicle arrival tracking

Configuration

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.

Setup

Claude Desktop

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

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

Claude Code CLI

claude mcp add tfl bunx -- @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):

FormatExampleNotes
ICS code1000129Most reliable — use output from stoppoint_search
Naptan ID940GZZLUVICReliable for tube/rail stations
PostcodeN1C4TBAlways resolves unambiguously
Coordinates51.5308,-0.1238Always unambiguous
Free textKing's CrossMay trigger disambiguation

Common station ICS codes:

StationICS code
King's Cross St. Pancras1000129
Victoria1000248
Waterloo1000254
London Bridge1000135
Paddington1000184
Liverpool Street1000134
Euston1000078
Canary Wharf1001006
Brixton1000023
Stratford1000222

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)

License

MIT

İlgili Sunucular