Tfl MCP Server

TfL MCP Server

Disclaimer: This is a community-built project. It is not affiliated with, endorsed by, or connected to Transport for London (TfL). This project consumes the publicly available TfL Unified API.

A MCP server that exposes the TfL (Transport for London) Unified API as tools, allowing AI assistants like Claude to query live London transport data.

Available in two implementations:

• Node.js (MCPB) — lightweight Desktop extension, recommended for Claude Desktop
• Java — Docker image or standalone ZIP, also supports HTTP/SSE transport

Getting Started

Step 1 — Add to Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Option A: Node.js MCPB (recommended)

Download tfl-mcp-server.mcpb from GitHub Releases and install it in Claude Desktop, or add manually:

{
  "mcpServers": {
    "tfl-mcp-server": {
      "command": "npx",
      "args": ["-y", "@oneill9/tfl-mcp-server"]
    }
  }
}

Option B: Docker

{
  "mcpServers": {
    "tfl-mcp-server": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/oneill9/tfl-mcp-server:latest"]
    }
  }
}

Step 2 — Add a TfL API key (recommended)

Without a key, TfL applies strict rate limits that will impact most real-world usage. Register a free key and pass it via the TFL_APP_KEY environment variable:

"env": { "TFL_APP_KEY": "your_key_here" }

Step 3 — Restart Claude Desktop and start asking questions

Example: "Is the Central line running normally?", "When is the next bus from Oxford Circus?"

For full setup details (Java direct, Docker options), see docs/installation.md.

Tools

Note: The server uses the /StopPoint/Search/{query} endpoint internally to automatically resolve stop names to NaPTAN IDs for the arrivals, crowding, and fares tools.

MCP Apps UI

The service_status tool includes MCP Apps support as a progressive enhancement. UI-capable hosts (e.g. Claude Desktop) can render an interactive service status board alongside the text response. Non-UI hosts continue to receive the standard text output.

• The UI is self-contained (inline HTML/CSS, no external assets)
• Structured JSON data is returned alongside the text fallback
• No additional setup is required — host support is detected automatically

See docs/tools.md for full details.

Authentication

This server is distributed as a Desktop extension (MCPB) using stdio transport. It does not implement OAuth or any server-side authentication.

The TfL API uses a simple API key (TFL_APP_KEY) that you supply as an environment variable. A key is strongly recommended — without one, TfL applies strict rate limits that will impact most real-world usage. Registration is free. No OAuth flow, login, or account beyond the TfL portal is required to use this MCP server.

Configuration

An API key is strongly recommended — without one, TfL's strict rate limits will impact most real-world usage. Registration is free at api-portal.tfl.gov.uk.

Running

Both implementations use stdio transport — JSON-RPC over stdin/stdout, the standard MCP transport for Claude Desktop.

# Node.js
cd node && npm run build && node dist/index.js

# Java
./gradlew run

For use with Claude Desktop, see docs/installation.md.

Testing

Node.js

Unit tests use a mock HTTP server — no network access or API key required:

cd node && npm test

Contract tests call the live TfL API:

cd node && TFL_APP_KEY=your_key_here npm run contractTest

Java

Unit tests use WireMock to stub the TfL API — no network access or API key required:

./gradlew test

Contract tests spin up the server as a real subprocess and call the live TfL API:

TFL_APP_KEY=your_key_here ./gradlew contractTest

Support

For questions, bug reports, or feature requests, please open an issue on GitHub Issues.

Privacy Policy

This MCP server acts as a local proxy between your AI assistant and the TfL Unified API. It does not collect, store, or transmit any personal data beyond what is required to forward your queries to TfL.

• Data collection: No user data is collected or logged by this server.
• Usage and storage: Queries are forwarded to TfL in real time and responses are returned immediately. No query history or results are persisted.
• Third-party sharing: Requests are forwarded to the TfL Unified API (api.tfl.gov.uk). See TfL's privacy policy for how TfL handles API usage data.
• Data retention: No data is retained. The server holds no state between requests.
• Contact: For privacy concerns, open an issue at https://github.com/oneill9/tfl-mcp-server/issues.

The full privacy policy is available at PRIVACY.md.

Compliance

This server has been reviewed for compliance with the Anthropic Software Directory Terms and Anthropic Software Directory Policy. See COMPLIANCE.md for the full compliance statement and maintainer commitments.

TfL API Reference

• Unified API: https://api.tfl.gov.uk/
• API Portal / Key Registration: https://api-portal.tfl.gov.uk/
• Swagger UI: https://api.tfl.gov.uk/swagger/ui/index.html