TomTom

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

Table of Contents

• Demo
• Security Notice
• Quick Start
  • Prerequisites
  • Installation
  • Configuration
  • Usage
• Integration Guides
• Available Tools
  • TomTom Orbis Maps (optional backend)
  • How dynamic map tool works
• Debug UI
• Local Development
  • Setup
  • Testing
  • Testing Requirements
  • Project Structure
• Troubleshooting
  • API Key Issues
  • Test Failures
  • Build Issues
• 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:

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

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	Comp

---

README truncated. View full README on GitHub.