TomTom MCP

TomTom MCP Tecnologia de localização para desenvolvedores

Documentação

Servidor MCP de Mapas TomTom

O Servidor MCP de Mapas TomTom simplifica o desenvolvimento geoespacial ao fornecer acesso contínuo aos serviços de localização da TomTom, incluindo busca, roteamento, trânsito e mapas interativos. Ele permite a integração fácil de dados de geolocalização precisos e exatos em fluxos de trabalho de IA e ambientes de desenvolvimento.

Demonstração

TomTom Maps MCP Demo

Sumário

Demonstração
Aviso de Segurança
Servidor MCP Remoto (Sem Necessidade de Instalação)
Início Rápido
Guias de Integração
Ferramentas Disponíveis
- Como a ferramenta de mapa dinâmico funciona
- Obtendo geometria de uma resposta de ferramenta
Interface de Depuração
Desenvolvimento Local
Solução de Problemas
Contribuição e Feedback
Segurança
Licença

Servidor MCP Remoto (Sem Necessidade de Instalação)

Pré-visualização Pública — O Servidor MCP Remoto de Mapas TomTom está atualmente em pré-visualização pública.

A maneira mais fácil de começar é conectar-se diretamente ao Servidor MCP hospedado pela TomTom — sem necessidade de Node.js, Docker ou configuração local.

Endpoint:

https://mcp.tomtom.com/maps

Pré-requisitos:

Uma chave de API TomTom válida com acesso ao Servidor MCP habilitado (consulte Gerenciamento de Chave de API)

Configuração Genérica de Cliente MCP

Adicione o seguinte à configuração do seu cliente MCP:

{
  "mcpServers": {
    "tomtom-mcp": {
      "type": "http",
      "url": "https://mcp.tomtom.com/maps",
      "headers": {
        "tomtom-api-key": "your_api_key_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Crie ou edite .vscode/mcp.json no seu espaço de trabalho:

{
  "servers": {
    "tomtom-mcp": {
      "type": "http",
      "url": "https://mcp.tomtom.com/maps",
      "headers": {
        "tomtom-api-key": "your_api_key_here"
      }
    }
  }
}

Claude Desktop

A opção mais rápida é instalar a extensão pré-compilada — consulte o Guia de Configuração do Claude Desktop para detalhes.

Alternativamente, configure o Claude Desktop para usar o servidor remoto diretamente editando seu arquivo de configuração:

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

{
  "mcpServers": {
    "tomtom-mcp": {
      "type": "http",
      "url": "https://mcp.tomtom.com/maps",
      "headers": {
        "tomtom-api-key": "your_api_key_here"
      }
    }
  }
}

Nota: Se o seu cliente MCP não suportar conexões HTTP remotas com cabeçalhos personalizados, use a configuração local em vez disso.

Aviso de Segurança

Manter as implantações locais do Servidor MCP de Mapas TomTom atualizadas é responsabilidade do cliente/operador MCP. A TomTom publica atualizações para corrigir vulnerabilidades conhecidas, mas não aplicar atualizações, patches ou configurações de segurança recomendadas à sua instância local pode expô-la a vulnerabilidades conhecidas.

Início Rápido

Pré-requisitos

Node.js 22.x
Chave de API TomTom

Como obter uma chave de API TomTom:

Crie uma conta de desenvolvedor no Portal do Desenvolvedor TomTom e faça login
Vá para Chaves de API e SDK no menu à esquerda.
Clique no botão vermelho Criar Chave.
Selecione todas as APIs disponíveis para garantir acesso total, atribua um nome à sua chave e clique em Criar.

Para mais detalhes, visite a Documentação de Gerenciamento de Chave de API TomTom.

Instalação

npm install @tomtom-org/tomtom-mcp@latest

# or run directly without installing
npx @tomtom-org/tomtom-mcp@latest

Configuração

Defina sua chave de API TomTom usando um dos seguintes métodos:

# Option 1: Use a .env file (recommended)
echo "TOMTOM_API_KEY=your_api_key" > .env

# Option 2: Environment variable
export TOMTOM_API_KEY=your_api_key

# Option 3: Pass as CLI argument
TOMTOM_API_KEY=your_api_key npx @tomtom-org/tomtom-mcp@latest

Variáveis de Ambiente

Variável	Descrição	Padrão
`TOMTOM_API_KEY`	Sua chave de API TomTom	-
`PORT`	Porta para o servidor HTTP	`3000`
`LOG_LEVEL`	Nível de registro: `debug`, `info`, `warn` ou `error`. Use `debug` para desenvolvimento local e ver todos os registros	`info`

Uso

Modo Stdio (Padrão - para assistentes de IA como Claude):

# Start MCP server via stdio
npx @tomtom-org/tomtom-mcp@latest

Modo HTTP (para aplicações web e integração de API):

pnpm run build            # Build first (required)
pnpm run start:http
# or run the built binary directly
node bin/tomtom-mcp-http.js

Ao executar no modo HTTP, você precisa incluir sua chave de API no cabeçalho tomtom-api-key:

tomtom-api-key: <API_KEY>

Por exemplo, para fazer uma solicitação usando curl:

curl --location 'http://localhost:3000/mcp' \
--header 'Accept: application/json,text/event-stream' \
--header 'tomtom-api-key: <API KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "tomtom-geocode",
    "arguments": {
        "query": "Amsterdam Central Station"
    }
  },
  "jsonrpc": "2.0",
  "id": 24
}'

A configuração do Docker também é definida para usar este modo HTTP com o mesmo método de autenticação.

Modo Docker (recomendado):

# Option 1: Using docker run directly
docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-maps-mcp:latest

# Option 2: Using Docker Compose (recommended for development)
# Clone the repository first
git clone https://github.com/tomtom-international/tomtom-maps-mcp.git
cd tomtom-maps-mcp

# Start the service
docker compose up

Ambas as opções do Docker executam o servidor no modo HTTP. Passe sua chave de API via cabeçalho tomtom-api-key conforme mostrado no exemplo curl do Modo HTTP acima.

Guias de Integração

O Servidor MCP de Mapas TomTom pode ser facilmente integrado em vários ambientes e ferramentas de desenvolvimento de IA.

Estes guias ajudam você a integrar o servidor MCP com suas ferramentas e ambientes:

Configuração do Claude Desktop - Instruções para configurar o Claude Desktop para funcionar com o servidor MCP de Mapas TomTom
Configuração do VS Code - Configurando um ambiente de desenvolvimento no Visual Studio Code
Integração com Cursor AI - Guia para integrar o servidor MCP de Mapas TomTom com Cursor AI
Integração com Windsurf - Instruções para configurar o Windsurf para usar o servidor MCP de Mapas TomTom
Integração com Smolagents - Exemplo mostrando como conectar agentes de IA Smolagents ao servidor MCP de Mapas TomTom.

Ferramentas Disponíveis

Ferramenta	Descrição	Documentação
`tomtom-geocode`	Geocodificação direta: endereço → coordenadas	https://developer.tomtom.com/geocoding-api/documentation/tomtom-orbis-maps/geocode
`tomtom-reverse-geocode`	Geocodificação reversa: coordenadas → endereço	https://developer.tomtom.com/reverse-geocoding-api/documentation/tomtom-orbis-maps/reverse-geocode
`tomtom-fuzzy-search`	Busca geral com tolerância a erros de digitação e sugestões	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/fuzzy-search
`tomtom-poi-search`	Busca de Pontos de Interesse (baseada em categorias)	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/points-of-interest-search
`tomtom-nearby`	Encontre POIs próximos a uma coordenada dentro de um raio	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/nearby-search
`tomtom-poi-categories`	Liste as categorias de POI disponíveis para busca	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/poi-categories
`tomtom-routing`	Calcule a rota ideal entre dois pontos	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
`tomtom-reachable-range`	Calcule a área de cobertura por orçamento de tempo ou distância	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-reachable-range
`tomtom-traffic`	Incidentes de trânsito e detalhes relacionados	https://developer.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/incident-details
`tomtom-dynamic-map`	Mapa interativo com marcadores personalizados, rotas e polígonos, renderizado pelo aplicativo MCP	https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/vector-style
`tomtom-ev-routing`	Planeje rotas de VE de longa distância com otimização automática de paradas de recarga	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/long-distance-ev-routing
`tomtom-search-along-route`	Encontre POIs (restaurantes, postos de gasolina, hotéis, etc.) ao longo de um corredor de rota	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/search-along-route
`tomtom-area-search`	Busque por lugares dentro de uma área geográfica (círculo, polígono ou caixa delimitadora)	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/geometry-search
`tomtom-ev-search`	Encontre estações de recarga de VE com disponibilidade em tempo real e tipos de conector	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/ev-charging-stations-availability
`tomtom-data-viz`	Visualize dados GeoJSON personalizados em um mapa base interativo TomTom (marcadores, mapas de calor, clusters, coropléticos)	https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/vector-style

Como a ferramenta de mapa dinâmico funciona

A ferramenta de mapa dinâmico não renderiza nada no lado do servidor. Ela resolve a solicitação em um estado de mapa — o estilo do mapa base a carregar, a viewport a abrir e fontes e camadas GeoJSON para os marcadores, rotas e polígonos solicitados — calculando qualquer routePlans através da API de Roteamento ao longo do caminho.

Esse estado é armazenado em cache e a ferramenta retorna seu viz_id. O aplicativo MCP o busca com a ferramenta tomtom-get-viz-data somente do aplicativo e desenha o mapa no lado do cliente, para que pan, zoom e cliques funcionem em um mapa ao vivo.

Como o mapa é desenhado pelo aplicativo, o visual requer um cliente MCP que suporte aplicativos MCP. Outros clientes recebem um resumo JSON do que o mapa mostra: sua view, marcadores, rotas (distância, tempo de viagem, atraso de trânsito) e áreas.

Referências:

Estilo de mapas TomTom Orbis: https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/vector-style

Obtendo geometria de uma resposta de ferramenta

Toda ferramenta aceita um parâmetro response_detail. As seis ferramentas que retornam geometria (tomtom-routing, tomtom-ev-routing, tomtom-reachable-range, tomtom-traffic, tomtom-area-search e tomtom-search-along-route) aceitam três valores; as demais aceitam compact e full.

Valor	Retorna
`compact` (padrão)	Campos essenciais e as coordenadas do ponto de um lugar. Sem geometria: linhas de rota, polígonos de alcance e locais de incidentes de trânsito são omitidos.
`geometry`	`compact`, mais uma chave `geometry` contendo essa geometria como uma FeatureCollection GeoJSON.
`full`	A resposta bruta da API: sem perdas, no formato próprio da API e muitas vezes maior.

O padrão é ajustado para uso conversacional, onde uma linha de rota consumiria a maior parte do contexto de um modelo sem benefício. Se você está construindo sobre o servidor e precisa das coordenadas em si, para desenhar o resultado no seu próprio mapa ou executar sua própria análise, solicite response_detail: "geometry". Use full apenas quando precisar de campos que compact descarta, ou da linha exata.

Para uma rota de Amsterdã a Berlim, geometry tem cerca de 22 KB: a linha de 8.000 pontos é simplificada para 1.000 vértices, no máximo 13 m do original. full tem cerca de 210 KB.

A FeatureCollection `geometry`

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": { "summary": { "lengthInMeters": 663425, "travelTimeInSeconds": 24453 } }
    }
  ],
  "geometry": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": { "type": "LineString", "coordinates": [[4.90413, 52.36761], [4.90419, 52.36755]] },
        "properties": {
          "route": 0,
          "simplification": { "original_points": 8151, "points": 1000, "max_error_m": 13 }
        }
      }
    ]
  }
}

Coordenadas seguem RFC 7946: [longitude, latitude], arredondadas para 5 casas decimais (cerca de 1,1 m). Anéis de polígonos são fechados.

Um feature por item. Seus properties contêm apenas uma chave de junção dando a posição do item no restante da resposta. Uma chave de junção é válida apenas dentro de uma única resposta; não a armazene como identificador.

Ferramenta	Features	`properties`
Roteamento	Um `LineString` por rota	`{"route": 0}`
Roteamento de VE	Um `LineString` por rota, depois um `Point` por parada de recarga	`{"route": 0}`, `{"route": 0, "leg": 1}` (a parada no final do trecho 1)
Alcance	Um `Polygon` por alcance, com seu orçamento	`{"range": 0, "budget_min": 30}`; também `budget_km`, `budget_fuel_l`, `budget_charge_pct`, `budget_remaining_charge_pct`
Trânsito	Um `Point` ou `LineString` por incidente, conforme retornado pela API	`{"incident": 12}`, correspondendo a `incidents[12]`
Busca de área	O limite de busca `Polygon`	`{"boundary": "circle"}`, `"polygon"` ou `"boundingBox"`
Busca ao longo da rota	A rota `LineString`	`{"route": 0}`

No máximo 1.000 vértices por feature. Linhas mais longas são simplificadas, e o feature então carrega simplification: as contagens de vértices original e retornada, e max_error_m, um limite superior em metros inteiros sobre a distância entre um vértice descartado e a linha retornada, incluindo o deslocamento do arredondamento de coordenadas para 5 decimais. Uma rota longa é precisa no zoom que mostra tudo dela, mas visivelmente aproximada ao ampliar; se max_error_m for grande demais para seu uso, solicite full. Um polígono que se cruzaria após a simplificação mantém mais vértices em vez disso, então pode exceder 1.000.
Sem índices de vértices. Seções e trechos de rota apontam para a linha original da API, que uma linha simplificada não corresponde mais, então respostas geometry descartam startPointIndex, endPointIndex e pointIndex.

O design está registrado em docs/adr/.

Nota: Hosts que suportam Aplicativos MCP renderizam o widget de mapa interativo a partir da resposta não cortada independentemente desta configuração, então compact não perde nada visualmente. O parâmetro show_ui solicita esse widget e é ignorado por hosts que não podem renderizá-lo; não é uma forma de obter coordenadas.

Interface de Depuração

Uma interface de depuração integrada permite testar visualmente as ferramentas MCP e seus widgets de mapa interativo sem precisar de um cliente de IA.

Início Rápido

pnpm run ui

Isso inicia tanto o servidor HTTP MCP (porta 3000) quanto o host da interface de depuração (porta 8080). Abra http://localhost:8080 no seu navegador.

Recursos

Navegador de ferramentas — barra lateral pesquisável listando todas as ferramentas disponíveis, com ícones distinguindo ferramentas habilitadas para mapas de ferramentas simples
Exemplos pré-preenchidos — cada ferramenta carrega com parâmetros de exemplo (incluindo show_ui: true para widgets de mapa)
Widgets de mapa ao vivo — ferramentas com recursos de UI renderizam mapas interativos da TomTom diretamente no navegador
Metadados de resposta — latência, tamanho da carga útil, contagem estimada de tokens, partes de conteúdo e carimbos de data/hora para cada chamada
Modo escuro / claro — alterne com o botão de tema ou siga a preferência do sistema
Atalhos de teclado — Cmd+Enter para executar, Cmd+K para pesquisar ferramentas

Requisitos

O servidor MCP deve estar em execução no modo HTTP (gerenciado automaticamente pelo pnpm run ui)
Uma TOMTOM_API_KEY válida no seu arquivo .env

Compilando a interface separadamente

O host da interface é um pacote de workspace (tomtom-mcp-app-host em ui/), então o pnpm install raiz já instalou suas dependências.

pnpm run ui:build                              # Build the UI
pnpm --filter tomtom-mcp-app-host start        # Start only the UI host (assumes MCP server is already running)

Desenvolvimento Local

Este projeto usa pnpm (>=11) como seu gerenciador de pacotes. Instale-o com npm install -g pnpm ou corepack enable. Linting e formatação são tratados pelo Biome.

Configuração

git clone https://github.com/tomtom-international/tomtom-maps-mcp.git

cd tomtom-maps-mcp

pnpm install

cp .env.example .env      # Add your API key in .env

pnpm run build            # Build TypeScript files

node ./bin/tomtom-mcp.js   # Start the MCP server

Testes

pnpm run build              # Build TypeScript
pnpm test                   # Run all tests
pnpm run test:all           # All tests (unit + stdio + http)

Requisitos de Teste

⚠️ Importante: Todos os testes exigem uma chave de API válida em .env, pois fazem chamadas reais de API (não simuladas). Isso consumirá sua cota de API.

Estrutura do Projeto

src/
├── apps/              # MCP App UI resources
├── handlers/          # Request handlers
├── schemas/           # Validation schemas
├── services/          # TomTom API wrappers
├── tools/             # MCP tool definitions
├── types/             # TypeScript type definitions
├── utils/             # Utilities
├── createServer.ts    # MCP Server creation logic
├── index.ts           # Main entry point (stdio)
└── indexHttp.ts       # HTTP server entry point

Solução de Problemas

Problemas com Chave de API

echo $TOMTOM_API_KEY  # Check if set

Falhas em Testes

ls -la .env          # Verify .env exists
cat .env             # Check API key

Problemas de Compilação

pnpm run build           # Rebuild
pnpm store prune         # Clear cache

Erros Proibidos (403)

Se você vir um erro informando "permissões ausentes", significa que sua chave de API não tem acesso aos serviços TomTom Orbis Maps ou EV, que sustentam todas as ferramentas deste servidor.

Nota: TomTom Orbis Maps e certos recursos de roteamento EV estão atualmente em Pré-visualização Pública. Eles podem não estar disponíveis em todas as contas de desenvolvedor por padrão.

Como solucionar:

Faça login no Portal do Desenvolvedor TomTom.
Garanta que todos os produtos disponíveis estejam selecionados para sua chave de API.
Se você ainda vir erros 403, sua conta pode ainda não ter acesso à pré-visualização do Orbis — solicite acesso pelo portal do desenvolvedor.

Contribuições e Feedback

Agradecemos contribuições para o TomTom Maps MCP Server! Consulte CONTRIBUTING.md para detalhes sobre como enviar pull requests, relatar problemas e sugerir melhorias.

Todas as contribuições devem aderir ao nosso Código de Conduta e ser assinadas de acordo com o Certificado de Origem do Desenvolvedor (DCO).

Abra problemas no repositório do GitHub

Segurança

Consulte nossa Política de Segurança para informações sobre como relatar vulnerabilidades de segurança e nossas práticas de segurança.

Licença

Este projeto é licenciado sob a Apache License 2.0 — consulte o arquivo LICENSE.md para detalhes.

TomTom MCP

Documentação

Servidor MCP de Mapas TomTom

Demonstração

Sumário

Servidor MCP Remoto (Sem Necessidade de Instalação)

Configuração Genérica de Cliente MCP

VS Code (GitHub Copilot)

Claude Desktop

Aviso de Segurança

Início Rápido

Pré-requisitos

Instalação

Configuração

Variáveis de Ambiente

Uso

Guias de Integração

Ferramentas Disponíveis

Como a ferramenta de mapa dinâmico funciona

Obtendo geometria de uma resposta de ferramenta

A FeatureCollection geometry

Interface de Depuração

Início Rápido

Recursos

Requisitos

Compilando a interface separadamente

Desenvolvimento Local

Configuração

Testes

Requisitos de Teste

Estrutura do Projeto

Solução de Problemas

Problemas com Chave de API

Falhas em Testes

Problemas de Compilação

Erros Proibidos (403)

Contribuições e Feedback

Segurança

Licença

A FeatureCollection `geometry`