{
  "markdown": "# TfL MCP Server\n\n<img src=\"docs/logo.svg\" alt=\"TfL MCP Server logo\" width=\"80\" align=\"right\"/>\n\n> **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](https://api.tfl.gov.uk/).\n\n[![GitHub release](https://img.shields.io/github/v/release/oneill9/tfl-mcp-server)](https://github.com/oneill9/tfl-mcp-server/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAn MCP server that exposes the [TfL (Transport for London) Unified API](https://api.tfl.gov.uk/) as tools, allowing AI assistants like Claude to query live London transport data.\n\nVersion 2 is a single Node.js 22 implementation using the MCP `2026-07-28` protocol revision. It supports stdio for local hosts, npm, and MCPB, plus stateless Streamable HTTP at `/mcp` for remote deployments.\n\n> **Protocol compatibility:** Streamable HTTP is modern-only MCP `2026-07-28`. The stdio entry point also accepts 2025-era initialization for desktop hosts such as Codex, while modern stdio clients continue to negotiate `2026-07-28`. Legacy HTTP/SSE is not supported.\n\n## Getting Started\n\n**Step 1 — Add to Claude Desktop**\n\nOpen your Claude Desktop config file:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Linux: `~/.config/Claude/claude_desktop_config.json`\n\n**Option A: Node.js MCPB (recommended)**\n\nDownload `tfl-mcp-server.mcpb` from [GitHub Releases](https://github.com/oneill9/tfl-mcp-server/releases) and install it in Claude Desktop.\n\n**Option B: npm**\n\nWith Node.js 22 or later installed, point Claude Desktop at the published package:\n\n```json\n{\n  \"mcpServers\": {\n    \"tfl-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@oneill9/tfl-mcp-server@2.0.0\"],\n      \"env\": { \"TFL_APP_KEY\": \"your_key_here\" }\n    }\n  }\n}\n```\n\n**Option C: Docker**\n\n```json\n{\n  \"mcpServers\": {\n    \"tfl-mcp-server\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"TFL_APP_KEY\", \"ghcr.io/oneill9/tfl-mcp-server:latest\"]\n    }\n  }\n}\n```\n\n**Step 2 — Add a TfL API key (recommended)**\n\nWithout a key, TfL applies strict rate limits that will impact most real-world usage. [Register a free key](https://api-portal.tfl.gov.uk/) and pass it via the `TFL_APP_KEY` environment variable. The Docker example's `-e TFL_APP_KEY` forwards this value into the container:\n\n```json\n\"env\": { \"TFL_APP_KEY\": \"your_key_here\" }\n```\n\n**Step 3 — Restart Claude Desktop and start asking questions**\n\nExample: *\"Is the Central line running normally?\"*, *\"When is the next bus from Oxford Circus?\"*\n\nFor source, Docker, and Streamable HTTP options, see [docs/installation.md](docs/installation.md).\n\n## Tools\n\n| Tool | Description | TfL Endpoint |\n|------|-------------|--------------|\n| `service_status` | Current status and disruptions by mode | `GET /Line/Mode/{modes}/Status` |\n| `arrivals` | Live arrivals at a stop by name | `GET /StopPoint/{naptan}/Arrivals` |\n| `journey` | Plan a journey between two points | `GET /Journey/JourneyResults/{from}/to/{to}` |\n| `bike_points` | List Santander Cycles docking stations | `GET /BikePoint` |\n| `crowding` | Live station crowding level by name | `GET /Crowding/{naptan}/Live` |\n| `fares` | Fare information between two named stops | `GET /StopPoint/{id}/FareTo/{targetId}` |\n\n> **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.\n\n### MCP Apps UI\n\nThe `service_status` tool includes [MCP Apps](https://modelcontextprotocol.io) 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.\n\n- The UI is self-contained (inline HTML/CSS, no external assets)\n- Structured JSON data is returned alongside the text fallback\n- No additional setup is required — host support is detected automatically\n\nSee [docs/tools.md](docs/tools.md) for full details.\n\n## Authentication\n\nThe MCPB and default container mode use stdio transport. The optional Streamable HTTP mode does not implement OAuth or any other server-side authentication; deploy it only behind an appropriate trusted access layer.\n\nThe 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.\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|----------------------|---------|-------------|\n| `TFL_APP_KEY` | *(none)* | TfL API key — register at [api-portal.tfl.gov.uk](https://api-portal.tfl.gov.uk/) |\n| `TFL_APP_ID` | *(none)* | TfL App ID — only needed for older API registrations that issued both an ID and key |\n| `MCP_MAX_REQUEST_BODY_BYTES` | `1048576` | Maximum JSON request body size accepted by Streamable HTTP |\n| `MCP_REQUEST_TIMEOUT_MS` | `30000` | Streamable HTTP request timeout in milliseconds |\n| `MCP_HEADERS_TIMEOUT_MS` | `10000` | Streamable HTTP header timeout in milliseconds; must not exceed the request timeout |\n\nAn 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](https://api-portal.tfl.gov.uk/).\n\n## Running from source\n\nNode.js 22 or later is required. Install from the lockfile and build before starting the server.\n\n```sh\ncd node\nnpm ci\nnpm run build\nnode dist/index.js\n```\n\nThat starts stdio transport. For stateless Streamable HTTP:\n\n```sh\ncd node\nHOST=127.0.0.1 PORT=8080 node dist/index.js --http\n```\n\nConnect an MCP `2026-07-28` client to `http://127.0.0.1:8080/mcp`. Set `MCP_ALLOWED_HOSTS` to a comma-separated hostname allowlist when serving under other hostnames.\n\nFor use with Claude Desktop, see [docs/installation.md](docs/installation.md).\n\n## Testing\n\nUnit tests use a mock HTTP server — no network access or API key required:\n\n```sh\ncd node && npm test\n```\n\nThe Streamable HTTP acceptance tests are included in `npm test`. Run the official frozen MCP `2026-07-28` requirement set separately (optional extension probes outside that set are not scored):\n\n```sh\ncd node && npm run test:conformance\n```\n\nThe conformance fixture registers the real production TfL tools and resource through the shared modern-only HTTP adapter. It also adds test-only diagnostic tools, resources, prompts, and flows needed by the referee's hard-coded probes; those diagnostics are not exposed by the production entry point.\n\nContract tests call the live TfL API:\n\n```sh\ncd node && TFL_APP_KEY=your_key_here npm run contractTest\n```\n\nBuild and smoke-test the packed npm CLI, MCPB, and container distributions with `bash scripts/test-distributions.sh`. The script skips container checks when Docker is unavailable.\n\n## Support\n\nFor questions, bug reports, or feature requests, please open an issue on [GitHub Issues](https://github.com/oneill9/tfl-mcp-server/issues).\n\n## Privacy Policy\n\nThis MCP server acts as a local proxy between your AI assistant and the [TfL Unified API](https://api.tfl.gov.uk/). It does not collect, store, or transmit any personal data beyond what is required to forward your queries to TfL.\n\n- **Data collection:** No analytics or telemetry is collected. Limited operational diagnostics are written to standard error but are not persisted by the server; a host may retain them under its own logging policy.\n- **Usage and storage:** Queries are forwarded to TfL in real time and responses are returned immediately. No query history or results are persisted.\n- **Third-party sharing:** Requests are forwarded to the TfL Unified API (`api.tfl.gov.uk`). See [TfL's privacy policy](https://tfl.gov.uk/corporate/privacy-and-cookies/) for how TfL handles API usage data.\n- **Data retention:** The server retains no data and holds no state between requests. Host-managed standard-error retention is outside the server's control.\n- **Contact:** For privacy concerns, open an issue at <https://github.com/oneill9/tfl-mcp-server/issues>.\n\nThe full privacy policy is available at [PRIVACY.md](PRIVACY.md).\n\n## Compliance\n\nThis server has been reviewed for compliance with the [Anthropic Software Directory Terms](https://support.claude.com/en/articles/13145338-anthropic-software-directory-terms) and [Anthropic Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy). See [COMPLIANCE.md](COMPLIANCE.md) for the full compliance statement and maintainer commitments.\n\n## TfL API Reference\n\n- Unified API: <https://api.tfl.gov.uk/>\n- API Portal / Key Registration: <https://api-portal.tfl.gov.uk/>\n- Swagger UI: <https://api.tfl.gov.uk/swagger/ui/index.html>\n",
  "bytes": 9037,
  "sha": "10c916ccb6537ab4261d953fba4a109b509fa200a74ada531eb150b0692ad1f9",
  "repo_slug": "oneill9/tfl-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_oneill9_tfl_mcp_server_1bd8f9b0/readme"
}