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
• Quick Start
  • Prerequisites
  • Installation
  • Configuration
  • Usage
• Integration
• Available Tools
• Contributing & Local Development
  • Setup
  • Testing
  • Project Structure
• Troubleshooting
• Contributing & Feedback
• License

---

Quick Start

Prerequisites

• Node.js 22+
• TomTom API key

How to obtain a TomTom API key:

1. Create a developer account on TomTom Developer Portal
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
npx @tomtom-org/tomtom-mcp@latest --key your_api_key

---

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):

# or
npm run start:http
# or after building the project
node bin/tomtom-mcp-http.js

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

Authorization: Bearer <API_KEY>

For example, to make a request using curl:

curl --location 'http://localhost:3000/mcp' \
--header 'Accept: application/json,text/event-stream' \
--header 'Authorization: Bearer <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.

# Get help
npx @tomtom-org/tomtom-mcp@latest --help

---

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

---

Orbis equivalents (optional backend)

By default the MCP tools use the Genesis TomTom APIs listed above. We also support using the "Orbis" backend for the same tools. To enable Orbis for all tools set the environment variable MAPS=ORBIS

Important: Orbis 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 Orbis for your developer account

How dynamic map tool works

We fetch a Map Style JSON (either Genesis or Orbis), 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:

• Genesis Map Styles v2: https://developer.tomtom.com/map-display-api/documentation/mapstyles/map-styles-v2
• Orbis style fetch: https://developer.tomtom.com/assets-api/documentation/tomtom-orbis-maps/styles-assets/fetch-style

---

Contributing & Local Development

Setup

git clone <repository>

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:comprehensive  # Integration tests

---

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/
├── tools/             # MCP tool definitions
├── services/          # TomTom API wrappers
├── schemas/           # Validation schemas
├── utils/             # Utilities
└── createServer.ts    # MCP Server creation logic
└── index.ts           # Main 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 NV