TomTom
STDIOOfficialMCP server providing TomTom geospatial services including search, routing, traffic and static maps
MCP server providing TomTom geospatial services including search, routing, traffic and static maps
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.
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.
# Install required dependencies via Homebrew brew install webp libuv webp icu4c jpeg-turbo glfw brew link icu4c --force
# 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
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:
For more details, visit the TomTom API Key Management Documentation.
npm install @tomtom-org/tomtom-mcp@latest # or run directly without installing npx @tomtom-org/tomtom-mcp@latest
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
| Variable | Description | Default |
|---|---|---|
TOMTOM_API_KEY | Your TomTom API key | - |
MAPS | Backend to use: GENESIS (default) or ORBIS | GENESIS |
ENABLE_DYNAMIC_MAPS | Enable or disable the dynamic maps feature | false |
Note about ENABLE_DYNAMIC_MAPS:
false) to avoid dependency issuestrue to enable dynamic maps after installing required dependenciestrue by default as all dependencies are pre-installedStdio 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 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 tomtom-api-key header:
tomtom-api-key: <API_KEY>
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: Genesis is the default backend (same as npm package) docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest # To use Orbis backend instead of default Genesis: docker run -p 3000:3000 -e MAPS=orbis 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 Genesis backend by default) docker compose up
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 }'
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:
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:
We fetch a Map Style JSON (either Genesis or Orbis), then use MapLibre (server-side) to:
The server converts the rendered image to PNG and returns as Base64 string.
References:
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
npm run build # Build TypeScript npm test # Run all tests npm run test:unit # Unit tests only npm run test:comprehensive # Integration tests
⚠️ Important: All tests require a valid API key in .env as they make real API calls (not mocked). This will consume your API quota.
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
If you encounter issues with native dependencies (especially for the dynamic map tool):
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
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.
By default, the dynamic map tool is disabled to avoid native dependency issues. To enable it:
ENABLE_DYNAMIC_MAPS=true in your environment or .env fileFor detailed build instructions, see the official MapLibre Native documentation:
echo $TOMTOM_API_KEY # Check if set
ls -la .env # Verify .env exists cat .env # Check API key
npm run build # Rebuild npm cache clean --force # Clear cache
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
Please see our Security Policy for information on reporting security vulnerabilities and our security practices.
This project is licensed under the Apache License 2.0 - see the LICENSE.md file for details.
Copyright (C) 2025 TomTom NV