TomTom MCP Server

What is TomTom MCP Server about? Provides seamless access to TomTom’s geolocation suite—including forward/reverse geocoding, fuzzy and POI search, routing, reachable range, traffic incidents, static and dynamic maps—through an MCP‑compatible server that can be consumed by AI agents or any HTTP client.

How to use TomTom MCP Server?

Install/run the server with npx @tomtom-org/tomtom-mcp@latest (or via Docker).
Supply a valid TomTom API key via a .env file, environment variable TOMTOM_API_KEY, or the CLI argument syntax.
Choose the backend (tomtom-maps default or tomtom-orbis-maps) through the MAPS env var or per‑request header tomtom-maps-backend.
Call tools using the MCP JSON‑RPC format over STDIO (for AI assistants) or HTTP POST to http://localhost:3000/mcp with the required headers (tomtom-api-key, optional tomtom-maps-backend).

Key Features of TomTom MCP Server

Multiple backends – Switch between TomTom Maps and TomTom Orbis Maps.
Extensive tool catalog – Geocode, reverse‑geocode, fuzzy search, POI search, nearby, routing, waypoint routing, reachable range, traffic, static map, dynamic map, plus Orbis‑only tools (EV routing, search‑along‑route, area search, EV‑search, data‑viz).
STDIO and HTTP modes – Direct integration with AI assistants (Claude, Cursor, etc.) or web applications.
Docker support – One‑line container deployment.
Debug UI – Interactive web UI for testing tools and visualizing map widgets.
Configurable logging – LOG_LEVEL control (debug, info, warn, error).

Use Cases of TomTom MCP Server

AI‑driven navigation assistants – Enable chat‑based agents to plan routes, find POIs, or report traffic.
Location‑aware planning bots – Automate delivery routing, EV charging stop optimization, or service area coverage calculations.
Map‑enhanced generation – Generate dynamic map images with custom markers for reports or visual content.
Geospatial data enrichment – Augment user queries with precise coordinates, address validation, or reverse‑geocoding in AI workflows.
Developer prototyping – Quickly prototype location‑centric features without building direct API calls.

FAQ from the TomTom MCP Server

Do I need a TomTom API key? Yes, a valid TOMTOM_API_KEY is required for all operations.
Can I switch backends at runtime? Set MAPS=tomtom-orbis-maps at startup for a fixed backend, or omit it and specify tomtom-maps-backend header per request.
Is Docker mandatory? No, the server can run via npx or after a local npm install.
Which tool needs the Orbis backend? tomtom-static-map works only with the default TomTom Maps backend; all other tools are available on both backends, with extra Orbis‑only tools listed above.
How do I test the server locally? Run npm run ui to launch both the HTTP server and the built‑in debug UI at http://localhost:8080.

TomTom MCP Server

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

Demo
Security Notice
Quick Start
Integration Guides
Available Tools
- TomTom Orbis Maps (optional backend)
- How dynamic map tool works
Debug UI
Local Development
Troubleshooting
Contributing & Feedback
Security
License

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:

Create a developer account on TomTom Developer Portal and Sign-in
Go to API & SDK Keys in the left-hand menu.
Click the red Create Key button.
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

Variable	Description	Default
`TOMTOM_API_KEY`	Your TomTom API key	-
`MAPS`	Backend to use: `tomtom-maps` (TomTom Maps) or `tomtom-orbis-maps` (TomTom Orbis Maps)	`tomtom-maps`
`PORT`	Port for the HTTP server	`3000`
`LOG_LEVEL`	Logging level: `debug`, `info`, `warn`, or `error`. Use `debug` for local development to see all logs	`info`

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:

Claude Desktop Setup - Instructions for configuring Claude Desktop to work with TomTom MCP server
VS Code Setup - Setting up a development environment in Visual Studio Code
Cursor AI Integration - Guide for integrating TomTom MCP server with Cursor AI
Windsurf Integration - Instructions for configuring Windsurf to use TomTom MCP server
Smolagents Integration - Example showing how to connect Smolagents AI agents to TomTom MCP server.

Available Tools

Tool	Description	Documentation
`tomtom-geocode`	Convert addresses to coordinates with global coverage	https://developer.tomtom.com/geocoding-api/documentation/geocode
`tomtom-reverse-geocode`	Get addresses from GPS coordinates	https://developer.tomtom.com/reverse-geocoding-api/documentation/reverse-geocode
`tomtom-fuzzy-search`	Intelligent search with typo tolerance	https://developer.tomtom.com/search-api/documentation/search-service/fuzzy-search
`tomtom-poi-search`	Find specific business categories	https://developer.tomtom.com/search-api/documentation/search-service/points-of-interest-search
`tomtom-nearby`	Discover services within a radius	https://developer.tomtom.com/search-api/documentation/search-service/nearby-search
`tomtom-routing`	Calculate optimal routes between locations	https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route
`tomtom-waypoint-routing`	Multi-stop route planning Routing API	https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route
`tomtom-reachable-range`	Determine coverage areas by time/distance	https://developer.tomtom.com/routing-api/documentation/tomtom-maps/calculate-reachable-range
`tomtom-traffic`	Real-time incidents data	https://developer.tomtom.com/traffic-api/documentation/traffic-incidents/traffic-incidents-service
`tomtom-static-map`	Generate custom map images	https://developer.tomtom.com/map-display-api/documentation/raster/static-image
`tomtom-dynamic-map`	Advanced map rendering with custom markers, routes, and traffic visualization	https://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.

Tool	Description	TomTom Orbis Maps API (documentation)
`tomtom-geocode`	Forward geocoding: address → coordinates	https://developer.tomtom.com/geocoding-api/documentation/tomtom-orbis-maps/geocode
`tomtom-reverse-geocode`	Reverse geocoding: coordinates → address	https://developer.tomtom.com/reverse-geocoding-api/documentation/tomtom-orbis-maps/reverse-geocode
`tomtom-fuzzy-search`	General search with typo tolerance and suggestions	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/fuzzy-search
`tomtom-poi-search`	Points of Interest (category-based) search	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/points-of-interest-search
`tomtom-nearby`	Find POIs near a coordinate within a radius	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/nearby-search
`tomtom-routing`	Calculate optimal route between two points	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
`tomtom-waypoint-routing`	Multi-stop / waypoint route planning	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-route
`tomtom-reachable-range`	Compute coverage area by time or distance budget	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/calculate-reachable-range
`tomtom-traffic`	Traffic incidents and related details	https://developer.tomtom.com/traffic-api/documentation/tomtom-orbis-maps/incident-details
`tomtom-dynamic-map`	Advanced map rendering with custom markers, routes, and traffic visualization	https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/raster-tile
`tomtom-ev-routing`	Plan long-distance EV routes with automatic charging stop optimization	https://developer.tomtom.com/routing-api/documentation/tomtom-orbis-maps/long-distance-ev-routing
`tomtom-search-along-route`	Find POIs (restaurants, gas stations, hotels, etc.) along a route corridor	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/search-along-route
`tomtom-area-search`	Search 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-search`	Find EV charging stations with real-time availability and connector types	https://developer.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/ev-charging-stations-availability
`tomtom-data-viz`	Visualize 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:

TomTom Map Tile API: https://developer.tomtom.com/map-display-api/documentation/raster/map-tile
TomTom Orbis Maps Tile API: https://developer.tomtom.com/map-display-api/documentation/tomtom-orbis-maps/raster-tile

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.

TomTom MCP Server

TomTom MCP Server Overview

TomTom MCP Server

TomTom MCP Server's README

TomTom MCP Server

Demo

Table of Contents

Security Notice

Quick Start

Prerequisites

Installation

Configuration

Environment Variables

Usage

Integration Guides

Available Tools

TomTom Orbis Maps (optional backend)

How dynamic map tool works

Debug UI

Quick Start

Features

Requirements

Building the UI separately

Local Development

Setup

Testing

Testing Requirements

Project Structure

Troubleshooting

API Key Issues

Test Failures

Build Issues

Contributing & Feedback

Security

License

TomTom MCP Server Reviews

Login Required

Similar MCP Servers like TomTom MCP Server

Git

Zed

Everything

Time

Cline

Context7 MCP

Daytona

Continue

GitHub MCP Server

Actions

TomTom MCP Server's Information

Configuration

Claude Code (Terminal)

Configure Clients