Quick Setup

Getting Started with TomTom MCP Server

The TomTom MCP Server enables AI assistants to access TomTom's location APIs through the Model Context Protocol (MCP). Follow these steps to quickly set up and start using TomTom MCP Server with your AI workflows.

Prerequisites

Before you begin, ensure you have:

TomTom API key - Sign up for a free account to get your API key
Node.js 22 or later installed on your system (specifically for the dynamic map tool we need Node 22.x due to dependency issues, rest all tools works with older/newer Node versions.)
An MCP-compatible AI client (Claude Desktop, Cursor, VS Code with Copilot, Smolagent, etc.)
Docker (optional, recommended for avoiding dependency issues)

Step 1: Install TomTom MCP Server

Choose one of the following installation methods:

Option A: NPM Package

The simplest way to use TomTom MCP Server is through the NPM package:

1# Run directly with npx (no installation required)
2# Set your API key as an environment variable
3export TOMTOM_API_KEY="your_api_key_here"
4
5# Then run the MCP server
6npx -y @tomtom-org/tomtom-mcp

Option B: Docker (Recommended)

Using Docker avoids native dependency issues, especially for the dynamic map tool:

1# Option 1: Using docker run directly
2# Note: Genesis is the default backend (same as npm package)
3docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest
4
5# To use Orbis backend instead of default Genesis:
6docker run -p 3000:3000 -e MAPS=orbis ghcr.io/tomtom-international/tomtom-mcp:latest
7
8# Option 2: Using Docker Compose (recommended for development)
9# Clone the repository first
10git clone https://github.com/tomtom-international/tomtom-mcp.git
11cd tomtom-mcp
12
13# Start the service (uses Genesis backend by default)
14docker compose up

Option C: Local Development

For developers who want to explore or modify the code from the open source repository:

1# Clone the repository
2git clone https://github.com/tomtom-international/tomtom-mcp
3
4# Navigate to the directory
5cd tomtom-mcp
6
7# Install dependencies
8npm install
9
10# Build the package
11npm run build
12
13# Run the server
14node bin/tomtom-mcp.js

HTTP Mode

TomTom MCP Server can also run in HTTP mode, which is useful for:

Sharing one MCP server instance across multiple applications
Integrating with web applications
Using with clients that support HTTP connections

To run in HTTP mode:

1
2with Docker (already runs in HTTP mode on port 3000)
3docker run -p 3000:3000 -e ghcr.io/tomtom-international/tomtom-mcp:latest

When using HTTP mode, include your API key in the Authorization header:

tomtom-api-key: your_api_key_here

For example, to make a test request using curl:

1curl --location 'http://localhost:3000/mcp' \
2--header 'Accept: application/json,text/event-stream' \
3--header 'tomtom-api-key: your_api_key_here' \
4--header 'Content-Type: application/json' \
5--data '{
6  "method": "tools/call",
7  "params": {
8    "name": "tomtom-geocode",
9    "arguments": {
10        "query": "Amsterdam Central Station"
11    }
12  },
13  "jsonrpc": "2.0",
14  "id": 24
15}'

Step 2: Configure Your MCP Client

Choose one of the following client configuration approaches:

Process-Based Configuration

Add the TomTom MCP Server to your AI client's configuration:

1{
"mcpServers": {
  "tomtom-mcp": {
    "command": "npx",
    "args": ["-y", "@tomtom-org/tomtom-mcp"],
    "env": {
      "TOMTOM_API_KEY": "your_api_key_here"
    }
  }
}
11}

Replace "your_api_key_here" with your actual TomTom API key. The env property ensures the API key is passed as an environment variable to the MCP server.

HTTP-Based Configuration

If you're running the MCP server in HTTP mode (recommended with Docker), configure your client to connect via HTTP:

1{
"mcpServers": {
  "tomtom-mcp": {
    "type": "http", 
    "url": "http://localhost:3000/mcp",
    "headers": {
      "tomtom-api-key": "your_api_key_here"
    }
  }
}
11}

This approach is recommended when:

Using Docker to run the MCP server
Wanting to separate the MCP server lifecycle from your AI client
Sharing one MCP server instance across multiple applications

Step 3: Additional Configuration Options

Backend Selection

TomTom MCP Server supports two map backends:

Genesis (default): The standard TomTom map backend
Orbis: TomTom's next-generation mapping platform (Public Preview)

To use Orbis instead of Genesis:

Set the MAPS=orbis environment variable
With Docker: docker run -p 3000:3000 -e MAPS=orbis ghcr.io/tomtom-international/tomtom-mcp:latest
With NPX: npx -y @tomtom-org/tomtom-mcp

Note: Orbis is currently in Public Preview and may require explicit enablement for your developer account. Contact TomTom Support for access.

Dynamic Map Tool

The dynamic map tool provides advanced map rendering capabilities but requires specific dependencies:

Node.js 22.x (specifically version 22.x)
Native dependencies for MapLibre GL Native
- macOS: brew install webp libuv webp icu4c jpeg-turbo glfw
- Linux: apt-get install libcurl4-openssl-dev libglfw3-dev libuv1-dev libicu-dev libpng-dev libjpeg-turbo8-dev libwebp-dev
- Windows: Requires Visual Studio 2022 with C++ or MSYS2 with specific packages

By default, this feature is disabled to avoid dependency issues. To enable it:

Set ENABLE_DYNAMIC_MAPS=true environment variable
Or use the Docker image which includes all dependencies pre-installed

Step 4: Test the Connection

Once configured, test that your AI assistant can access TomTom's services by asking a simple location-based question:

What's at the coordinates 52.3676, 4.9041?

Your AI assistant should be able to use the TomTom MCP Server to retrieve the address and other location details from the TomTom APIs.