TomTom MCP

Location technology for developers

GitHub

TomTom MCP Server

NPM Version License

The TomTom MCP Server simplifies geospatial development by providing seamless access to TomTom’s location services, including search, routing, traffic and static maps data. It enables easy integration of precise and accurate geolocation data into AI workflows and development environments.

Demo

TomTom MCP Demo

Table of Contents

Remote MCP Server (No Installation Required)

Public Preview — The TomTom Remote MCP Server is currently in public preview.

The easiest way to get started is to connect directly to TomTom's hosted MCP Server — no Node.js, Docker, or local setup needed.

Endpoint:

https://mcp.tomtom.com/maps

Prerequisites:

Generic MCP Client Configuration

Add the following to your MCP client configuration:

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

Selecting a Map Backend

Add the optional tomtom-maps-backend header to choose your backend:

TomTom Maps (default):

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

TomTom Orbis Maps:

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

If the tomtom-maps-backend header is omitted, the server defaults to TomTom Maps.

VS Code (GitHub Copilot)

Create or edit .vscode/mcp.json in your workspace:

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

Claude Desktop

The quickest option is to install the pre-built extension — see the Claude Desktop Setup guide for details.

Alternatively, configure Claude Desktop to use the remote server directly by editing your configuration file:

  • 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"
      }
    }
  }
}

Note: If your MCP client does not support remote HTTP connections with custom headers, use the local setup instead.

Security Notice

Keeping local deployments of the TomTom MCP Server up-to-date is the responsibility of the MCP client/operator. TomTom publishes updates to address known vulnerabilities, but failing to apply updates, patches, or recommended security configurations to your local instance may expose it to known vulnerabilities.

Quick Start

Prerequisites

  • Node.js 22.x
  • TomTom API key

How to obtain a TomTom API key:

  1. Create a developer account on TomTom Developer Portal and Sign-in
  2. Go to API & SDK Keys in the left-hand menu.
  3. Click the red Create Key button.
  4. Select all available APIs to ensure full access, assign a name to your key, and click Create.

For more details, visit the TomTom API Key Management Documentation.

Installation

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

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

Configuration

Set your TomTom API key using one of the following methods:

# 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

Environment Variables

VariableDescriptionDefault
TOMTOM_API_KEYYour TomTom API key-
MAPSBackend to use: tomtom-maps (TomTom Maps) or tomtom-orbis-maps (TomTom Orbis Maps)tomtom-maps
PORTPort for the HTTP server3000
LOG_LEVELLogging level: debug, info, warn, or error. Use debug for local development to see all logsinfo

Usage

Stdio Mode (Default - for AI assistants like Claude):

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

HTTP Mode (for web applications and API integration):

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

When running in HTTP mode, you need to include your API key in the tomtom-api-key header. You can also optionally set the maps backend per-request using the tomtom-maps-backend header:

tomtom-api-key: <API_KEY>
tomtom-maps-backend: tomtom-maps        # or tomtom-orbis-maps

Note: The tomtom-maps-backend header is only used when the server is started without the MAPS env var (dual-backend mode). If MAPS is set at startup, the header is ignored and the server uses the fixed backend.

For example, to make a request using 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
}'

The Docker setup is also configured to use this HTTP mode with the same authentication method.

Docker Mode (recommended):

# Option 1: Using docker run directly
# Note: TomTom Maps is the default backend (same as npm package)
docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest

# To use TomTom Orbis Maps backend instead:
docker run -p 3000:3000 -e MAPS=tomtom-orbis-maps ghcr.io/tomtom-international/tomtom-mcp:latest

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

# Start the service (uses TomTom Maps backend by default)
docker compose up

Both Docker options run the server in HTTP mode. Pass your API key via the tomtom-api-key header as shown in the HTTP Mode curl example above.

Integration Guides

TomTom MCP Server can be easily integrated into various AI development environments and tools.

These guides help you integrate the MCP server with your tools and environments:

Available Tools

ToolDescriptionDocumentation
tomtom-geocodeConvert addresses to coordinates with global coveragehttps://developer.tomtom.com/geocoding-api/documentation/geocode
tomtom-reverse-geocodeGet addresses from GPS coordinateshttps://developer.tomtom.com/reverse-geocoding-api/documentation/reverse-geocode
tomtom-fuzzy-searchIntelligent search with typo tolerancehttps://developer.tomtom.com/search-api/documentation/search-service/fuzzy-search
tomtom-poi-searchFind specific business categorieshttps://developer.tomtom.com/search-api/documentation/search-service/points-of-interest-search
tomtom-nearbyDiscover services within a radiushttps://developer.tomtom.com/search-api/documentation/search-service/nearby-search
tomtom-routingCalculate optimal routes between locationshttps://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route
tomtom-waypoint-routingMulti-stop route planning Routing APIhttps://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route
tomtom-reachable-rangeDetermine coverage areas by time/distancehttps://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-reachable-range
tomtom-trafficReal-time incidents datahttps://developer.tomtom.com/traffic-api/documentation/traffic-incidents/traffic-incidents-service
tomtom-static-mapGenerate custom map imageshttps://developer.tomtom.com/map-display-api/documentation/raster/static-image
tomtom-dynamic-mapAdvanced map rendering with custom markers, routes, and traffic visualizationhttps://developer.tomtom.com/map-display-api/documentation/raster/map-tile

TomTom Orbis Maps (optional backend)

By default the MCP tools use TomTom Maps APIs listed above. We also support using TomTom Orbis Maps for the same tools. To enable TomTom Orbis Maps for all tools set the environment variable MAPS=tomtom-orbis-maps.

Note: The Orbis Maps backend includes all the tools from TomTom Maps plus additional Orbis-exclusive tools: tomtom-ev-routing, tomtom-search-along-route, tomtom-area-search, tomtom-ev-search, and tomtom-data-viz. The tomtom-static-map tool is only available with the default TomTom Maps backend.

ToolDescriptionTomTom Orbis Maps API (documentation)
tomtom-geocodeForward geocoding: address → coordinateshttps://developer.tomtom.com/geocoding-api/documentation/tomtom-orbis-maps/geocode
tomtom-reverse-geocodeReverse geocoding: coordinates → addresshttps://developer.tomtom.com/reverse-geocoding-api/documentation/tomtom-orbis-maps/reverse-geocode
tomtom-fuzzy-searchGeneral search with typo tolerance and suggestionshttps://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/fuzzy-search
tomtom-poi-searchPoints of Interest (category-based) searchhttps://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/points-of-interest-search
tomtom-nearbyFind POIs near a coordinate within a radiushttps://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/nearby-search
tomtom-routingCalculate optimal route between two pointshttps://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
tomtom-waypoint-routingMulti-stop / waypoint route planninghttps://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
tomtom-reachable-rangeCompute coverage area by time or distance budgethttps://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-reachable-range
tomtom-trafficTraffic incidents and related detailshttps://developer.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/incident-details
tomtom-dynamic-mapAdvanced map rendering with custom markers, routes, and traffic visualizationhttps://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/raster-tile
tomtom-ev-routingPlan long-distance EV routes with automatic charging stop optimizationhttps://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/long-distance-ev-routing
tomtom-search-along-routeFind POIs (restaurants, gas stations, hotels, etc.) along a route corridorhttps://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/search-along-route
tomtom-area-searchSearch for places within a geographic area (circle, polygon, or bounding box)https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/geometry-search
tomtom-ev-searchFind EV charging stations with real-time availability and connector typeshttps://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/ev-charging-stations-availability
tomtom-data-vizVisualize custom GeoJSON data on an interactive TomTom basemap (markers, heatmaps, clusters, choropleths)https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/raster-tile

How dynamic map tool works

The dynamic map tool fetches raster tiles from TomTom (either TomTom Maps or TomTom Orbis Maps), then uses skia-canvas (server-side) to:

  • stitch map tiles into a single canvas at the appropriate zoom level;
  • add markers, routes, polygons, and other overlays;
  • render the final composited image.

The server converts the rendered image to PNG and returns it as a Base64 string.

References:

Debug UI

A built-in debug UI lets you visually test MCP tools and their interactive map widgets without needing an AI client.

Quick Start

npm run ui

This starts both the MCP HTTP server (port 3000) and the debug UI host (port 8080). Open http://localhost:8080 in your browser.

Features

  • Tool browser — searchable sidebar listing all available tools, with icons distinguishing map-enabled tools from plain tools
  • Pre-filled examples — each tool loads with example parameters (including show_ui: true for map widgets)
  • Live map widgets — tools with UI resources render interactive TomTom maps directly in the browser
  • Response metadata — latency, payload size, estimated token count, content parts, and timestamps for every call
  • Dark / light mode — toggle with the theme button or follows system preference
  • Keyboard shortcuts — Cmd+Enter to run, Cmd+K to search tools

Requirements

  • The MCP server must be running in HTTP mode (handled automatically by npm run ui)
  • A valid TOMTOM_API_KEY in your .env file
  • To see map widgets, use the TomTom Orbis Maps backend (MAPS=tomtom-orbis-maps in .env)

Building the UI separately

npm run ui:build    # Install deps + build the UI
cd ui && npm start  # Start only the UI host (assumes MCP server is already running)

Local Development

Setup

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

cd tomtom-mcp

npm install

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

npm run build             # Build TypeScript files

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

Testing

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

Testing Requirements

⚠️ Important: All tests require a valid API key in .env as they make real API calls (not mocked). This will consume your API quota.

Project Structure

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

Troubleshooting

API Key Issues

echo $TOMTOM_API_KEY  # Check if set

Test Failures

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

Build Issues

npm run build            # Rebuild
npm cache clean --force  # Clear cache

Contributing & Feedback

We welcome contributions to the TomTom MCP Server! Please see CONTRIBUTING.md for details on how to submit pull requests, report issues, and suggest improvements.

All contributions must adhere to our Code of Conduct and be signed-off according to the Developer Certificate of Origin (DCO).

Open issues on the GitHub repo

Security

Please see our Security Policy for information on reporting security vulnerabilities and our security practices.

License

This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details.

Copyright (C) 2025 TomTom Navigation B.V.

Related Servers

NotebookLM Web Importer

Import web pages and YouTube videos to NotebookLM with one click. Trusted by 200,000+ users.

Install Chrome Extension