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

Related MCP server: MCP IP Geolocation Server

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

• Contributing & Local Development

  • Setup

  • Testing

  • Testing Requirements

  • Project Structure

• Troubleshooting

  • Native Dependency Issues

  • Dynamic Map Tool Issues

  • 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 (strict requirement for dynamic map tool, other tools may work with older/newer versions)

• TomTom API key

• OS-level dependencies for MapLibre GL Native:

  • macOS:

    # Install required dependencies via Homebrew brew install webp libuv webp icu4c jpeg-turbo glfw brew link icu4c --force

  • Ubuntu/Debian:

    # Install essential dependencies for MapLibre Native rendering sudo apt-get install -y libcurl4-openssl-dev libglfw3-dev libuv1-dev \ libicu-dev libpng-dev libjpeg-turbo8-dev libwebp-dev

  • Windows: Choose one of the two options:

    • Using Visual Studio:

      • Install Visual Studio 2022 with "Desktop Development with C++"

    • Using MSYS2:

      • Install MSYS2, then run:

        pacman -S --needed mingw-w64-x86_64-angleproject mingw-w64-x86_64-curl-winssl \ mingw-w64-x86_64-glfw mingw-w64-x86_64-icu mingw-w64-x86_64-libjpeg-turbo \ mingw-w64-x86_64-libpng mingw-w64-x86_64-libwebp mingw-w64-x86_64-libuv

💡 Note: For any issues with native dependencies or the dynamic map tool, please refer to the Troubleshooting section.

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

Configuration

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

Environment Variables

Note about :

• By default, the dynamic map tool is disabled (false) to avoid dependency issues

• Set to true to enable dynamic maps after installing required dependencies

• In Docker containers, this is set to true by default as all dependencies are pre-installed

Usage

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

HTTP Mode (for web applications and API integration):

When running in HTTP mode, you need to include your API key in the tomtom-api-key header:

For example, to make a request using curl:

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

Docker Mode (recommended):

Integration Guides

2. Connect via HTTP client: Send requests to http://localhost:3000/mcp with your API key in the tomtom-api-key header. 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

• WinSurf 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

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=orbis

Important: TomTom Orbis Maps tools are currently in Public Preview and require explicit enablement for developer accounts. To request access, contact TomTom Sales:

• Public Preview details: https://developer.tomtom.com/public-preview

• Contact Sales to enable TomTom Orbis Maps for your developer account

How dynamic map tool works

We fetch a Map Style JSON (either from TomTom Maps or TomTom Orbis Maps), then use MapLibre (server-side) to:

• add markers, routes, polygons and other layers defined by the style and request;

• render all layers into an image using that style.

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

References:

• TomTom Maps Styles v2: https://developer.tomtom.com/map-display-api/documentation/mapstyles/map-styles-v2

• TomTom Orbis Maps style fetch: https://developer.tomtom.com/assets-api/documentation/tomtom-orbis-maps/styles-assets/fetch-style

Contributing & Local Development

Setup

Testing

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

Troubleshooting

Native Dependency Issues

If you encounter issues with native dependencies (especially for the dynamic map tool):

1. Use Docker instead: Our Docker image includes all required dependencies pre-configured:

   docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest # or with Docker Compose (recommended for development) docker compose up

2. Connect via HTTP client: Send requests to http://localhost:3000/mcp with your API key in the tomtom-api-key header.

This approach isolates all native dependencies inside the container while providing the same functionality.

Dynamic Map Tool Issues

By default, the dynamic map tool is disabled to avoid native dependency issues. To enable it:

1. Ensure Node.js 22.x: The dynamic map tool specifically requires Node.js version 22.x

2. Install required dependencies: Follow the platform-specific instructions in the Prerequisites section

3. Enable dynamic maps: Set ENABLE_DYNAMIC_MAPS=true in your environment or .env file

For detailed build instructions, see the official MapLibre Native documentation:

• macOS Build Guide

• Linux Build Guide

• Windows Build Guide (MSVC)

• Windows Build Guide (MSYS2)

API Key Issues

Test Failures

Build Issues

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.