TomTom MCP

Tecnología de ubicación para desarrolladores

Documentación

Servidor MCP de Mapas TomTom

El Servidor MCP de Mapas TomTom simplifica el desarrollo geoespacial al proporcionar acceso fluido a los servicios de ubicación de TomTom, incluyendo búsqueda, rutas, tráfico y mapas interactivos. Permite una integración sencilla de datos de geolocalización precisos y exactos en flujos de trabajo de IA y entornos de desarrollo.

Demo

TomTom Maps MCP Demo

Tabla de Contenidos

Demo
Aviso de Seguridad
Servidor MCP Remoto (Sin Instalación Requerida)
Inicio Rápido
Guías de Integración
Herramientas Disponibles
- Cómo funciona la herramienta de mapa dinámico
- Cómo obtener geometría de una respuesta de herramienta
Interfaz de Depuración
Desarrollo Local
Solución de Problemas
Contribuciones y Comentarios
Seguridad
Licencia

Servidor MCP Remoto (Sin Instalación Requerida)

Vista Previa Pública — El Servidor MCP Remoto de Mapas TomTom se encuentra actualmente en vista previa pública.

La forma más sencilla de comenzar es conectarse directamente al Servidor MCP alojado de TomTom — sin necesidad de Node.js, Docker o configuración local.

Punto de conexión:

https://mcp.tomtom.com/maps

Requisitos previos:

Una clave de API de TomTom válida con acceso al Servidor MCP habilitado (consulte Gestión de Claves de API)

Configuración Genérica del Cliente MCP

Agregue lo siguiente a la configuración de su 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)

Cree o edite .vscode/mcp.json en su espacio de trabajo:

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

Claude Desktop

La opción más rápida es instalar la extensión precompilada — consulte la Guía de Configuración de Claude Desktop para más detalles.

Alternativamente, configure Claude Desktop para usar el servidor remoto directamente editando su archivo de configuración:

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: Si su cliente MCP no admite conexiones HTTP remotas con encabezados personalizados, use la configuración local en su lugar.

Aviso de Seguridad

Mantener las implementaciones locales del Servidor MCP de Mapas TomTom actualizadas es responsabilidad del cliente/operador MCP. TomTom publica actualizaciones para abordar vulnerabilidades conocidas, pero no aplicar actualizaciones, parches o configuraciones de seguridad recomendadas a su instancia local puede exponerla a vulnerabilidades conocidas.

Inicio Rápido

Requisitos Previos

Node.js 22.x
Clave de API de TomTom

Cómo obtener una clave de API de TomTom:

Cree una cuenta de desarrollador en el Portal de Desarrolladores de TomTom e inicie sesión
Vaya a Claves de API y SDK en el menú de la izquierda.
Haga clic en el botón rojo Crear Clave.
Seleccione todas las API disponibles para garantizar acceso completo, asigne un nombre a su clave y haga clic en Crear.

Para más detalles, visite la Documentación de Gestión de Claves de API de TomTom.

Instalación

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

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

Configuración

Establezca su clave de API de TomTom usando uno de los siguientes 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

Variables de Entorno

Variable	Descripción	Predeterminado
`TOMTOM_API_KEY`	Su clave de API de TomTom	-
`PORT`	Puerto para el servidor HTTP	`3000`
`LOG_LEVEL`	Nivel de registro: `debug`, `info`, `warn` o `error`. Use `debug` para desarrollo local y ver todos los registros	`info`

Uso

Modo Stdio (Predeterminado - para asistentes de IA como Claude):

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

Modo HTTP (para aplicaciones web e integración de API):

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

Cuando se ejecuta en modo HTTP, debe incluir su clave de API en el encabezado tomtom-api-key:

tomtom-api-key: <API_KEY>

Por ejemplo, para hacer una solicitud 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
}'

La configuración de Docker también está diseñada para usar este modo HTTP con el mismo método de autenticación.

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 opciones de Docker ejecutan el servidor en modo HTTP. Pase su clave de API a través del encabezado tomtom-api-key como se muestra en el ejemplo de curl del Modo HTTP anterior.

Guías de Integración

El Servidor MCP de Mapas TomTom se puede integrar fácilmente en diversos entornos y herramientas de desarrollo de IA.

Estas guías le ayudan a integrar el servidor MCP con sus herramientas y entornos:

Configuración de Claude Desktop - Instrucciones para configurar Claude Desktop para trabajar con el servidor MCP de Mapas TomTom
Configuración de VS Code - Configuración de un entorno de desarrollo en Visual Studio Code
Integración con Cursor AI - Guía para integrar el servidor MCP de Mapas TomTom con Cursor AI
Integración con Windsurf - Instrucciones para configurar Windsurf para usar el servidor MCP de Mapas TomTom
Integración con Smolagents - Ejemplo que muestra cómo conectar agentes de IA de Smolagents al servidor MCP de Mapas TomTom.

Herramientas Disponibles

Herramienta	Descripción	Documentación
`tomtom-geocode`	Geocodificación directa: dirección → coordenadas	https://developer.tomtom.com/geocoding-api/documentation/tomtom-orbis-maps/geocode
`tomtom-reverse-geocode`	Geocodificación inversa: coordenadas → dirección	https://developer.tomtom.com/reverse-geocoding-api/documentation/tomtom-orbis-maps/reverse-geocode
`tomtom-fuzzy-search`	Búsqueda general con tolerancia a errores tipográficos y sugerencias	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/fuzzy-search
`tomtom-poi-search`	Búsqueda de Puntos de Interés (basada en categorías)	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/points-of-interest-search
`tomtom-nearby`	Encontrar POIs cerca de una coordenada dentro de un radio	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/nearby-search
`tomtom-poi-categories`	Listar las categorías de POI disponibles para búsqueda	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/poi-categories
`tomtom-routing`	Calcular la ruta óptima entre dos puntos	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
`tomtom-reachable-range`	Calcular el área de cobertura por presupuesto de tiempo o distancia	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-reachable-range
`tomtom-traffic`	Incidentes de tráfico y detalles relacionados	https://developer.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/incident-details
`tomtom-dynamic-map`	Mapa interactivo con marcadores personalizados, rutas y polígonos, renderizado por la aplicación MCP	https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/vector-style
`tomtom-ev-routing`	Planificar rutas EV de larga distancia con optimización automática de paradas de carga	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/long-distance-ev-routing
`tomtom-search-along-route`	Encontrar POIs (restaurantes, gasolineras, hoteles, etc.) a lo largo de un corredor de ruta	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/search-along-route
`tomtom-area-search`	Buscar lugares dentro de un área geográfica (círculo, polígono o cuadro delimitador)	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/geometry-search
`tomtom-ev-search`	Encontrar estaciones de carga EV con disponibilidad en tiempo real y tipos de conector	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/ev-charging-stations-availability
`tomtom-data-viz`	Visualizar datos GeoJSON personalizados en un mapa base interactivo de TomTom (marcadores, mapas de calor, clústeres, coropletas)	https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/vector-style

Cómo funciona la herramienta de mapa dinámico

La herramienta de mapa dinámico no renderiza nada en el servidor. Resuelve la solicitud en un estado de mapa — el estilo del mapa base a cargar, la vista a abrir, y las fuentes y capas GeoJSON para los marcadores, rutas y polígonos solicitados — calculando cualquier routePlans a través de la API de Rutas en el proceso.

Ese estado se almacena en caché y la herramienta devuelve su viz_id. La aplicación MCP lo obtiene con la herramienta tomtom-get-viz-data exclusiva de la aplicación y dibuja el mapa en el lado del cliente, por lo que desplazarse, hacer zoom y hacer clic funcionan en un mapa en vivo.

Debido a que el mapa lo dibuja la aplicación, la visualización requiere un cliente MCP que admita aplicaciones MCP. Otros clientes reciben un resumen JSON de lo que muestra el mapa: su vista, marcadores, rutas (distancia, tiempo de viaje, retraso de tráfico) y áreas.

Referencias:

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

Cómo obtener geometría de una respuesta de herramienta

Cada herramienta acepta un parámetro response_detail. Las seis herramientas que devuelven geometría (tomtom-routing, tomtom-ev-routing, tomtom-reachable-range, tomtom-traffic, tomtom-area-search y tomtom-search-along-route) aceptan tres valores; las demás aceptan compact y full.

Valor	Devuelve
`compact` (predeterminado)	Campos esenciales y las coordenadas del punto de un lugar. Sin geometría: líneas de ruta, polígonos de rango alcanzable y ubicaciones de incidentes de tráfico se omiten.
`geometry`	`compact`, más una clave `geometry` que contiene esa geometría como una FeatureCollection GeoJSON.
`full`	La respuesta cruda de la API: sin pérdidas, en la forma propia de la API, y muchas veces más grande.

El valor predeterminado está optimizado para uso conversacional, donde una línea de ruta consumiría la mayor parte del contexto de un modelo sin beneficio. Si está construyendo sobre el servidor y necesita las coordenadas en sí, para dibujar el resultado en su propio mapa o ejecutar su propio análisis, solicite response_detail: "geometry". Use full solo cuando necesite campos que compact omite, o la línea exacta.

Para una ruta de Ámsterdam a Berlín, geometry es de aproximadamente 22 KB: la línea de 8,000 puntos se simplifica a 1,000 vértices, a lo sumo 13 m del original. full es de aproximadamente 210 KB.

La 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 siguen RFC 7946: [longitude, latitude], redondeadas a 5 decimales (aproximadamente 1.1 m). Los anillos de polígono están cerrados.

Una característica por elemento. Sus properties contienen solo una clave de unión que da la posición del elemento en el resto de la respuesta. Una clave de unión es válida solo dentro de una respuesta; no la almacene como identificador.

Herramienta	Características	`properties`
Rutas	Una `LineString` por ruta	`{"route": 0}`
Rutas EV	Una `LineString` por ruta, luego una `Point` por parada de carga	`{"route": 0}`, `{"route": 0, "leg": 1}` (la parada al final del tramo 1)
Rango alcanzable	Una `Polygon` por rango, con su presupuesto	`{"range": 0, "budget_min": 30}`; también `budget_km`, `budget_fuel_l`, `budget_charge_pct`, `budget_remaining_charge_pct`
Tráfico	Una `Point` o `LineString` por incidente, tal como la devuelve la API	`{"incident": 12}`, coincidiendo con `incidents[12]`
Búsqueda de área	El límite de búsqueda `Polygon`	`{"boundary": "circle"}`, `"polygon"` o `"boundingBox"`
Búsqueda a lo largo de la ruta	La `LineString` de la ruta	`{"route": 0}`

Como máximo 1,000 vértices por característica. Las líneas más largas se simplifican, y la característica lleva entonces simplification: los recuentos de vértices original y devuelto, y max_error_m, un límite superior en metros enteros de la distancia entre un vértice eliminado y la línea devuelta, incluido el desplazamiento por redondear coordenadas a 5 decimales. Una ruta larga es precisa en el zoom que muestra todo, pero visiblemente aproximada al hacer zoom; si max_error_m es demasiado grande para su uso, solicite full. Un polígono que se cruzaría a sí mismo después de la simplificación conserva más vértices en su lugar, por lo que puede exceder 1,000.
Sin índices de vértices. Las secciones y tramos de ruta apuntan a la línea original de la API, que una línea simplificada ya no coincide, por lo que las respuestas geometry omiten startPointIndex, endPointIndex y pointIndex.

El diseño está documentado en docs/adr/.

Nota: Los hosts que admiten Aplicaciones MCP renderizan el widget de mapa interactivo desde la respuesta sin recortar independientemente de esta configuración, por lo que compact no pierde nada visualmente. El parámetro show_ui solicita ese widget y es ignorado por hosts que no pueden renderizarlo; no es una forma de obtener coordenadas.

Interfaz de Depuración

Una interfaz de depuración integrada le permite probar visualmente las herramientas MCP y sus widgets de mapa interactivo sin necesidad de un cliente de IA.

Inicio Rápido

pnpm run ui

Esto inicia tanto el servidor HTTP MCP (puerto 3000) como el host de la interfaz de depuración (puerto 8080). Abra http://localhost:8080 en su navegador.

Características

Explorador de herramientas — panel lateral con búsqueda que lista todas las herramientas disponibles, con iconos que distinguen las herramientas habilitadas para mapas de las herramientas simples
Ejemplos prellenados — cada herramienta se carga con parámetros de ejemplo (incluyendo show_ui: true para widgets de mapas)
Widgets de mapas en vivo — las herramientas con recursos de interfaz de usuario renderizan mapas interactivos de TomTom directamente en el navegador
Metadatos de respuesta — latencia, tamaño de carga útil, recuento estimado de tokens, partes de contenido y marcas de tiempo para cada llamada
Modo oscuro / claro — alterna con el botón de tema o sigue la preferencia del sistema
Atajos de teclado — Cmd+Enter para ejecutar, Cmd+K para buscar herramientas

Requisitos

El servidor MCP debe estar ejecutándose en modo HTTP (gestionado automáticamente por pnpm run ui)
Una TOMTOM_API_KEY válida en tu archivo .env

Compilar la interfaz de usuario por separado

El host de la interfaz de usuario es un paquete del espacio de trabajo (tomtom-mcp-app-host en ui/), por lo que la raíz pnpm install ya instaló sus dependencias.

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)

Desarrollo Local

Este proyecto utiliza pnpm (>=11) como su gestor de paquetes. Instálalo con npm install -g pnpm o corepack enable. El linting y el formateo están gestionados por Biome.

Configuración

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

Pruebas

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

Requisitos de Pruebas

⚠️ Importante: Todas las pruebas requieren una clave de API válida en .env ya que realizan llamadas reales a la API (no simuladas). Esto consumirá tu cuota de API.

Estructura del Proyecto

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

Solución de Problemas

Problemas con la Clave de API

echo $TOMTOM_API_KEY  # Check if set

Fallos en las Pruebas

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

Problemas de Compilación

pnpm run build           # Rebuild
pnpm store prune         # Clear cache

Errores Prohibidos (403)

Si ves un error que indica "faltan permisos", significa que tu clave de API no tiene acceso a los servicios de TomTom Orbis Maps o EV, que respaldan todas las herramientas de este servidor.

Nota: TomTom Orbis Maps y ciertas funciones de enrutamiento EV están actualmente en Vista Previa Pública. Puede que no estén disponibles en todas las cuentas de desarrollador de forma predeterminada.

Cómo solucionarlo:

Inicia sesión en el Portal de Desarrolladores de TomTom.
Asegúrate de que todos los productos disponibles estén seleccionados para tu clave de API.
Si aún ves errores 403, tu cuenta puede no tener acceso a la vista previa de Orbis todavía — solicita acceso a través del portal de desarrolladores.

Contribuciones y Comentarios

¡Agradecemos las contribuciones al Servidor MCP de TomTom Maps! Consulta CONTRIBUTING.md para obtener detalles sobre cómo enviar solicitudes de extracción, informar problemas y sugerir mejoras.

Todas las contribuciones deben adherirse a nuestro Código de Conducta y estar firmadas de acuerdo con el Certificado de Origen del Desarrollador (DCO).

Abre problemas en el repositorio de GitHub

Seguridad

Consulta nuestra Política de Seguridad para obtener información sobre cómo informar vulnerabilidades de seguridad y nuestras prácticas de seguridad.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 — consulta el archivo LICENSE.md para más detalles.

TomTom MCP

Documentación

Servidor MCP de Mapas TomTom

Demo

Tabla de Contenidos

Servidor MCP Remoto (Sin Instalación Requerida)

Configuración Genérica del Cliente MCP

VS Code (GitHub Copilot)

Claude Desktop

Aviso de Seguridad

Inicio Rápido

Requisitos Previos

Instalación

Configuración

Variables de Entorno

Uso

Guías de Integración

Herramientas Disponibles

Cómo funciona la herramienta de mapa dinámico

Cómo obtener geometría de una respuesta de herramienta

La FeatureCollection geometry

Interfaz de Depuración

Inicio Rápido

Características

Requisitos

Compilar la interfaz de usuario por separado

Desarrollo Local

Configuración

Pruebas

Requisitos de Pruebas

Estructura del Proyecto

Solución de Problemas

Problemas con la Clave de API

Fallos en las Pruebas

Problemas de Compilación

Errores Prohibidos (403)

Contribuciones y Comentarios

Seguridad

Licencia

La FeatureCollection `geometry`