TfL

tfl-mcp

Servidor MCP para a API Unificada de Transporte de Londres — linhas, jornadas, pontos de parada, chegadas, pontos de bicicleta, ocupação, interrupções rodoviárias e muito mais via stdio.

Instalação

bunx @daanrongen/tfl-mcp

Ferramentas (80 no total)

Domínio	Ferramentas	Cobertura
AccidentStats	accident_stats	Acidentes rodoviários por ano
AirQuality	air_quality	Previsões de poluição ao vivo (NO2, O3, PM10, PM2.5, SO2)
BikePoint	bike_points_all, bike_point_search, bike_point_by_id	Disponibilidade de Santander Cycles
Cabwise	cabwise_search	Táxis licenciados e minicabs próximos a um local
Journey	journey_plan, journey_modes	Planejador de jornadas completo (todos os modos)
Line	14 ferramentas	Status, rotas, interrupções, chegadas, horários, sequências de paradas
Mode	mode_active_service_types, mode_arrivals	Informações de serviço entre modos
Occupancy	5 ferramentas	Estacionamentos, docks de bicicletas, conectores de carregamento EV
Place	7 ferramentas	Busca, consulta geográfica, ruas por CEP, tipos de lugares
Road	8 ferramentas	Status TLRN, interrupções, fechamentos, obras rodoviárias
Search	5 ferramentas	Busca de texto completo no site/dados da TfL
StopPoint	17 ferramentas	Busca, chegadas, interrupções, lotação, rotas, pontos de táxi, estacionamentos
Vehicle	3 ferramentas	Conformidade ULEZ, sobretaxa de emissões, rastreamento de chegada de veículos

Configuração

Chave de API (opcional, mas recomendada)

Registre-se para obter uma chave gratuita em https://api-portal.tfl.gov.uk/. Sem uma, as solicitações são limitadas a ~500/dia.

Configuração

Claude Desktop

Edite ~/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

Desenvolvimento

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

Inspeção local

bun run inspect inicia o Inspetor MCP contra a compilação local:

bun run build && bun run inspect

Isso abre a interface do Inspetor no seu navegador, onde você pode chamar qualquer ferramenta interativamente e inspecionar os formatos de solicitação/resposta.

Planejador de jornadas — IDs de localização

O modo de falha mais comum é passar um nome de texto livre para journey_plan, o que faz a TfL retornar uma resposta de desambiguação 300. A ferramenta lida com isso de forma graciosa e retorna IDs sugeridos de parameterValue para tentar novamente.

Formatos de ID preferidos (do mais ao menos confiável):

Formato	Exemplo	Notas
Código ICS	1000129	Mais confiável — use a saída de stoppoint_search
ID Naptan	940GZZLUVIC	Confiável para estações de metrô/trem
CEP	N1C4TB	Sempre resolve sem ambiguidade
Coordenadas	51.5308,-0.1238	Sempre sem ambiguidade
Texto livre	King's Cross	Pode acionar desambiguação

Códigos ICS de estações comuns:

Estação	Código ICS
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

Arquitetura

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)

Licença

MIT