### Local Development Setup

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Steps to set up the TomTom MCP project for local development. Includes cloning the repository, installing dependencies, configuring the environment, building TypeScript files, and starting the MCP server.

```bash
git clone https://github.com/tomtom-international/tomtom-mcp.git

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

--------------------------------

### TomTom MCP Server - Quick Start

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Instructions for setting up and running the TomTom MCP Server, including prerequisites, installation, and configuration.

```APIDOC
## TomTom MCP Server - Quick Start

### Description
This section provides a quick start guide for setting up and running the TomTom MCP Server. It covers the necessary prerequisites, installation steps, and configuration options.

### Prerequisites
- Node.js 22.x
- TomTom API key (obtainable from the [TomTom Developer Portal](https://developer.tomtom.com/))

### Installation
To install the TomTom MCP Server, run one of the following commands:

```bash
npm install @tomtom-org/tomtom-mcp@latest

# or run directly without installing
npx @tomtom-org/tomtom-mcp@latest
```

### Configuration
Configure your TomTom API key using one of the following methods:

**Option 1: Using a `.env` file (Recommended)**
Create a `.env` file in your project root and add the following line:

```
TOMTOM_API_KEY=your_api_key
```

**Option 2: Using an Environment Variable**
Set the `TOMTOM_API_KEY` environment variable:

```bash
export TOMTOM_API_KEY=your_api_key
```

**Option 3: Passing as a CLI Argument**
Provide the API key directly when running the command:

```bash
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. | `info`      |
```

--------------------------------

### Install TomTom MCP Server

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Installs the TomTom MCP Server package using npm or runs it directly using npx. This is the initial step for using the server's functionalities.

```bash
npm install @tomtom-org/tomtom-mcp@latest

# or run directly without installing
npx @tomtom-org/tomtom-mcp@latest
```

--------------------------------

### Start TomTom MCP Server in HTTP Mode

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Provides commands to build and start the TomTom MCP Server in HTTP mode, suitable for web applications and API integrations. It also shows how to run the built binary directly.

```bash
npm run build             # Build first (required)
npm run start:http
# or run the built binary directly
node bin/tomtom-mcp-http.js
```

--------------------------------

### Install TomTom MCP Server via npm

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Installs the TomTom MCP package globally or runs it directly using npx. This is the primary method for setting up the server on a local development machine.

```bash
# Install the package
npm install @tomtom-org/tomtom-mcp@latest

# Or run directly without installing
npx @tomtom-org/tomtom-mcp@latest
```

--------------------------------

### Configure TomTom MCP HTTP Server

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Provides an example of setting up an HTTP server for the TomTom MCP, including port configuration, backend selection, and graceful shutdown handling.

```typescript
import { createHttpServer, HttpServerOptions } from "@tomtom-org/tomtom-mcp";

const options: HttpServerOptions = {
  port: 3000,
  fixedBackend: "tomtom-orbis-maps",
  allowedOrigins: "http://localhost:8080,https://myapp.com"
};

const { app, httpServer, shutdown } = await createHttpServer(options);

process.on("SIGTERM", async () => {
  await shutdown();
  process.exit(0);
});
```

--------------------------------

### Configure TomTom MCP in Windsurf via STDIO

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/windsurf-setup.md

Configuration snippet for the Windsurf mcp_config.json file to run the TomTom MCP server using npx. This setup requires Node.js 22+ and a valid TomTom API key.

```json
{
  "mcpServers": {
     "tomtom-mcp": {
        "command": "npx",
        "args": ["-y","@tomtom-org/tomtom-mcp@latest"],
        "env": {
         "TOMTOM_API_KEY": "<your_API_KEY>"
        }
     }
  }
}
```

--------------------------------

### Configure TomTom MCP Server via Stdio

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/smolagents/smolagents-setup.md

Configures the StdioServerParameters to launch the TomTom MCP server using npx. This method requires passing the TomTom API key directly through the environment variables.

```python
server_parameters = StdioServerParameters(
	command="npx", 
	args=["-y", "@tomtom-org/tomtom-mcp@latest"], 
	env={
		"TOMTOM_API_KEY": "<your_API_KEY>"}, # replace with your TomTom API key
)
```

--------------------------------

### Configure TomTom MCP Server in VS Code Settings

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/vscode-setup.md

Defines the MCP server configuration within the .vscode/settings.json file. This setup enables the TomTom MCP server to run via npx, requiring a valid TomTom API key.

```json
{
  "servers": {
    "tomtom-mcp": {
      "command": "npx",
      "args": ["-y", "@tomtom-org/tomtom-mcp@latest"],
      "env": {
        "TOMTOM_API_KEY": "<your_API_KEY>"
      }
    }
  }
}
```

--------------------------------

### Start MCP Debug UI

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

This command starts both the MCP HTTP server on port 3000 and the debug UI host on port 8080. After execution, access the debug UI by navigating to http://localhost:8080 in your web browser.

```bash
npm run ui
```

--------------------------------

### Deploy TomTom MCP Server via Docker

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/smolagents/smolagents-setup.md

Commands to run the TomTom MCP server as a standalone service using Docker or Docker Compose. This is the recommended approach for production-like stability.

```bash
# Run using Docker in the background
docker run -d -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest

# Or with Docker Compose (after cloning the repository)
docker compose up -d
```

--------------------------------

### Connect Smolagents to TomTom MCP via HTTP

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/smolagents/smolagents-setup.md

Demonstrates how to initialize a ToolCollection in Python to connect to an existing TomTom MCP HTTP server. It includes logic to list available tools and execute geocoding queries.

```python
from smolagents import ToolCollection

# Connect to the MCP server running on localhost:3000
with ToolCollection.from_mcp(
	{"url": "http://localhost:3000/mcp", 
	 "headers": {"tomtom-api-key": "<your_API_KEY>"}, 
	 "transport": "streamable-http"}, 
	trust_remote_code=True
) as collection:
	# List all available tools
	for tool in collection.tools:
		print(tool.name)
		
	# Use the tools in your agent
	# Example: Use geocoding
	# result = collection.tools_dict["tomtom-geocode"].call({"query": "Amsterdam Central Station"})
	# print(result)
```

--------------------------------

### Run TomTom MCP Server via Docker

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/vscode-setup.md

Commands to deploy the TomTom MCP server as an HTTP service using Docker or Docker Compose. This allows for independent server management and cross-tool compatibility.

```bash
# Run using Docker
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

# Or with Docker Compose
docker compose up
```

--------------------------------

### Manual TomTom MCP Server Configuration for Claude Desktop (JSON)

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/claude-desktop-setup.md

This snippet shows how to manually configure the TomTom MCP server within Claude Desktop's JSON configuration file. It requires Node.js 22+ and specifies the command to run, arguments, and environment variables, including the essential TomTom API key.

```json
{
  "mcpServers": {
     "tomtom-mcp": {
        "command": "npx",
        "args": ["-y", "@tomtom-org/tomtom-mcp@latest"],
        "env": {
           "TOMTOM_API_KEY": "<your_API_KEY>"
        }
     }
  }
}
```

--------------------------------

### Configure TomTom MCP Server in Cursor via STDIO

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/cursor-setup.md

This JSON configuration is used within Cursor's 'Add Custom MCP' settings to initialize the TomTom MCP server using npx. It requires a valid TomTom API key provided through the environment variables.

```json
{
    "mcpServers": {
        "tomtom-mcp": {
            "command": "npx",
            "args": ["-y", "@tomtom-org/tomtom-mcp@latest"],
            "env": {
                "TOMTOM_API_KEY": "<your_API_KEY>"
            }
        }
    }
}
```

--------------------------------

### Render Dynamic Map with Markers and Routes using TomTom Dynamic Map

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Renders custom map images with markers, routes, polygons, and area overlays using server-side rendering. This example includes multiple markers, a circle polygon, and a pedestrian route plan. The response is a base64-encoded PNG image.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-dynamic-map", \
      "arguments": { \
        "center": { "lat": 52.3676, "lon": 4.9041 }, \
        "zoom": 14, \
        "width": 1000, \
        "height": 800, \
        "markers": [ \
          { "lat": 52.3676, "lon": 4.9041, "label": "Amsterdam Central", "priority": "high" }, \
          { "lat": 52.36, "lon": 4.8852, "label": "Rijksmuseum", "category": "Museum" }, \
          { "lat": 52.3745, "lon": 4.8979, "label": "Anne Frank House", "category": "Museum" } \
        ], \
        "polygons": [ \
          { \
            "type": "circle", \
            "center": { "lat": 52.3676, "lon": 4.9041 }, \
            "radius": 1000, \
            "fillColor": "rgba(0,123,255,0.2)", \
            "strokeColor": "#007bff", \
            "label": "1km radius" \
          } \
        ], \
        "routePlans": [ \
          { \
            "origin": { "lat": 52.3676, "lon": 4.9041, "label": "Start" }, \
            "destination": { "lat": 52.36, "lon": 4.8852, "label": "End" }, \
            "travelMode": "pedestrian", \
            "color": "#FF4444" \
          } \
        ], \
        "showLabels": true, \
        "show_ui": true \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 11 \
  }'

# Response includes:
# - Base64-encoded PNG image
# - viz_id for interactive MCP App (when show_ui: true)
```

--------------------------------

### Deploy TomTom MCP Server using Docker

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/cursor-setup.md

Commands to run the TomTom MCP server in HTTP mode using Docker containers. These commands expose the service on port 3000 and allow for optional backend configuration via environment variables.

```bash
# Run using Docker
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

# Or with Docker Compose (after cloning the repository)
docker compose up
```

--------------------------------

### Configure VS Code for HTTP MCP Server

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/vscode-setup.md

Configures VS Code to connect to an externally running TomTom MCP HTTP server. Requires specifying the server URL and authentication headers.

```json
{
  "servers": {
    "tomtom-mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "tomtom-api-key": "<your_API_KEY>",
        "tomtom-maps-backend": "tomtom-maps"
      }
    }
  }
}
```

--------------------------------

### POST /mcp (tomtom-reachable-range)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Calculates the geographic area reachable from a starting point based on time, distance, or energy constraints.

```APIDOC
## POST /mcp (tomtom-reachable-range)

### Description
Determine the geographic area reachable within a specified time, distance, or energy budget. Returns a polygon boundary representing the coverage area from a starting point.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **method** (string) - Required - Must be "tools/call"
- **params.name** (string) - Required - Must be "tomtom-reachable-range"
- **params.arguments.origin** (object) - Required - {lat, lon} coordinates
- **params.arguments.timeBudgetInSec** (integer) - Optional - Time budget in seconds
- **params.arguments.distanceBudgetInMeters** (integer) - Optional - Distance budget in meters
- **params.arguments.travelMode** (string) - Required - e.g., "car"

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-reachable-range",
    "arguments": {
      "origin": { "lat": 52.3676, "lon": 4.9041 },
      "timeBudgetInSec": 1800,
      "travelMode": "car"
    }
  }
}

### Response
#### Success Response (200)
- **boundary** (array) - Polygon coordinates defining reachable area
- **center** (object) - Origin point coordinates
```

--------------------------------

### Generate Static Map Image with TomTom Static Map

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Creates custom static map images with specified center coordinates, zoom levels, and style options. This example generates a PNG image with a basic layer and main style. The response is a base64-encoded map image.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-static-map", \
      "arguments": { \
        "center": { "lat": 52.3676, "lon": 4.9041 }, \
        "zoom": 15, \
        "width": 800, \
        "height": 600, \
        "style": "main", \
        "layer": "basic", \
        "format": "png", \
        "language": "en-US" \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 10 \
  }'

# Response includes base64-encoded map image
# Style options: "main" (daytime), "night" (dark theme)
# Layer options: "basic" (streets), "labels" (text only), "hybrid" (satellite)
```

--------------------------------

### Configure Cursor for HTTP-based MCP Server

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/docs/cursor-setup.md

JSON configuration for connecting Cursor to a standalone TomTom MCP server running in HTTP mode. It specifies the server URL and required headers for authentication and backend selection.

```json
{
  "mcpServers": {
    "tomtom-mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "tomtom-api-key": "<your_API_KEY>",
        "tomtom-maps-backend": "tomtom-maps"
      }
    }
  }
}
```

--------------------------------

### Perform TomTom Geocoding via HTTP API

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Uses the MCP HTTP API to convert addresses into geographic coordinates. This example demonstrates geocoding '1600 Pennsylvania Ave, Washington DC' with specific country and language settings.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "tools/call",
    "params": {
      "name": "tomtom-geocode",
      "arguments": {
        "query": "1600 Pennsylvania Ave, Washington DC",
        "limit": 5,
        "countrySet": "US",
        "language": "en-US"
      }
    },
    "jsonrpc": "2.0",
    "id": 1
  }'
```

--------------------------------

### Calculate Reachable Area with TomTom Reachable Range

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Determines the geographic area reachable within a specified time, distance, or energy budget from a starting point. This example uses a time budget and car travel mode. The response includes a polygon boundary of the coverage area.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-reachable-range", \
      "arguments": { \
        "origin": { "lat": 52.3676, "lon": 4.9041 }, \
        "timeBudgetInSec": 1800, \
        "travelMode": "car", \
        "routeType": "fastest", \
        "traffic": true, \
        "avoid": ["tollRoads", "ferries"], \
        "response_detail": "compact" \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 8 \
  }'

# Alternative: distance-based range
# "distanceBudgetInMeters": 20000

# Response includes:
# - boundary: polygon coordinates defining reachable area
# - center: origin point
```

--------------------------------

### Build UI Separately

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Commands to build the UI separately. Assumes the MCP server is already running. Requires Node.js and npm.

```bash
npm run ui:build
cd ui && npm start
```

--------------------------------

### Integrate TomTom MCP Server with TypeScript

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Shows how to initialize the TomTom MCP server using the SDK and connect it to a stdio transport for use with AI assistants.

```typescript
import { createServer, ServerConfig } from "@tomtom-org/tomtom-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const config: ServerConfig = {
  apiKey: process.env.TOMTOM_API_KEY,
  mapsBackend: "tomtom-orbis-maps",
  userAgent: "MyApp/1.0"
};

const server = await createServer(config);
const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### Troubleshoot .env File

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Bash commands to verify the existence and content of the .env file, which should contain the API key.

```bash
ls -la .env
cat .env
```

--------------------------------

### Configure TomTom API Key

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Demonstrates methods for setting the TomTom API key, essential for authenticating with TomTom services. It includes using a .env file, environment variables, or passing it as a CLI argument.

```bash
# 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
```

--------------------------------

### Run TomTom MCP Server with Docker

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Shows how to run the TomTom MCP Server using Docker, which is the recommended mode. It maps the container's port to the host machine.

```bash
# 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
```

--------------------------------

### Troubleshoot Build Issues

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Commands to resolve build issues by rebuilding the project or clearing the npm cache.

```bash
npm run build
npm cache clean --force
```

--------------------------------

### Perform TomTom Reverse Geocoding via HTTP API

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Uses the MCP HTTP API to convert geographic coordinates (latitude and longitude) into human-readable addresses. This example reverses geocodes a specific location in Amsterdam.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "tools/call",
    "params": {
      "name": "tomtom-reverse-geocode",
      "arguments": {
        "lat": 52.3676,
        "lon": 4.9041,
        "radius": 100,
        "language": "en-US"
      }
    },
    "jsonrpc": "2.0",
    "id": 2
  }'
```

--------------------------------

### Testing Commands

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Commands for building and running tests within the TomTom MCP project. Supports full test suites, unit tests, and combined tests.

```bash
npm run build
npm test
npm run test:unit
npm run test:all
```

--------------------------------

### Check TomTom MCP Server Health via HTTP

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Performs a health check on the TomTom MCP Server by sending an HTTP GET request to the `/health` endpoint. The response provides server status, version, mode, and active backends.

```bash
curl http://localhost:3000/health
```

--------------------------------

### Deploy TomTom MCP Server with Docker

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Commands to run the TomTom MCP server using standalone Docker or Docker Compose. The standalone command demonstrates how to switch to the TomTom Orbis Maps backend using environment variables.

```bash
docker run -p 3000:3000 -e MAPS=tomtom-orbis-maps ghcr.io/tomtom-international/tomtom-mcp:latest
```

```bash
git clone https://github.com/tomtom-international/tomtom-mcp.git
cd tomtom-mcp
docker compose up
```

--------------------------------

### Registering a New Tool in TomTom MCP

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/Adding_new_tools.md

Demonstrates how to register a newly implemented tool by importing it and adding it to the list of available tools in the server bootstrap file.

```typescript
import { elevationTool } from './tools/elevationTool';

const tools = [
  ...existingTools,
  elevationTool
];
```

--------------------------------

### Find Real-Time Traffic Incidents with TomTom Traffic

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Retrieves real-time traffic incidents such as accidents, road closures, construction, and congestion within a specified bounding box. This example filters for present incidents and returns detailed information including severity and delay estimates.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-traffic", \
      "arguments": { \
        "bbox": "-74.02,40.70,-73.96,40.80", \
        "maxResults": 20, \
        "categoryFilter": "0,6,7,8", \
        "timeValidityFilter": "present", \
        "language": "en-GB" \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 9 \
  }'

# Category filter values:
# 0 - Accident, 1 - Fog, 2 - Dangerous Conditions, 3 - Rain
# 4 - Ice, 5 - Lane Restrictions, 6 - Lane Closure
# 7 - Road Closure, 8 - Road Works, 9 - Wind, 10 - Flooding

# Response includes array of incidents with:
# - type, severity, description
# - delay: estimated delay in seconds
# - from/to: affected road segment
# - geometry: incident location coordinates
```

--------------------------------

### TomTom MCP Server - Usage Modes

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Details on how to use the TomTom MCP Server in different modes: Stdio, HTTP, and Docker.

```APIDOC
## TomTom MCP Server - Usage Modes

### Description
This section details the different modes in which the TomTom MCP Server can be operated: Stdio mode for AI assistants, HTTP mode for web applications and API integration, and Docker mode for containerized deployments.

### Stdio Mode (Default)
This mode is suitable for AI assistants like Claude and is the default when running the server without specific flags.

```bash
# Start MCP server via stdio
npx @tomtom-org/tomtom-mcp@latest
```

### HTTP Mode
This mode is designed for web applications and API integrations. It requires a build step before starting.

```bash
npm run build             # Build first (required)
npm run start:http
# or run the built binary directly
node bin/tomtom-mcp-http.js
```

**Authentication and Headers:**
When running in HTTP mode, include your API key in the `tomtom-api-key` header. You can also specify 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 effective if the server is started without the `MAPS` environment variable (dual-backend mode). If `MAPS` is set during startup, this header is ignored.

**Example Request (curl):**

```bash
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
}'
```

### Docker Mode
This is the recommended mode for deployment using Docker.

**Option 1: Using `docker run` directly**

```bash
# TomTom Maps is the default backend (same as npm package)
docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest
```

The Docker setup is configured to use HTTP mode with the same authentication method as described above.
```

--------------------------------

### Configure TomTom MCP Server Environment Variables

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Sets environment variables to configure the TomTom MCP Server. Essential variables include the API key, with optional settings for backend selection, HTTP port, and logging level.

```bash
# Required: Your TomTom API key
export TOMTOM_API_KEY=your_api_key

# Optional: Backend selection (default: tomtom-maps)
# Use tomtom-orbis-maps for additional EV and data visualization tools
export MAPS=tomtom-orbis-maps

# Optional: HTTP server port (default: 3000)
export PORT=3000

# Optional: Logging level (debug, info, warn, error)
export LOG_LEVEL=info
```

--------------------------------

### Troubleshoot API Key

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Bash command to check if the TOMTOM_API_KEY environment variable is set.

```bash
echo $TOMTOM_API_KEY
```

--------------------------------

### Dynamic Map Rendering

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Tools for rendering custom map images with overlays.

```APIDOC
## [TOOL] tomtom-dynamic-map

### Description
Fetches map tiles, stitches them into a canvas, and renders custom markers, routes, or polygons.

### Parameters
#### Request Body
- **center** (string) - Required - Map center coordinates.
- **zoom** (integer) - Required - Zoom level.
- **overlays** (array) - Optional - List of GeoJSON objects to render.

### Response
#### Success Response (200)
- **image** (string) - Base64 encoded PNG image of the map.
```

--------------------------------

### POST /mcp (tomtom-ev-search)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Finds EV charging stations with real-time availability, connector types, and power level filtering.

```APIDOC
## POST /mcp (tomtom-ev-search)

### Description
Find EV charging stations with real-time availability, connector types, and power levels. Returns detailed information about charger status.

### Method
POST

### Endpoint
http://localhost:3000/mcp

### Request Body
- **params.name** (string) - Required - "tomtom-ev-search"
- **params.arguments.query** (string) - Optional - Search term
- **params.arguments.connectorTypes** (array) - Optional - List of supported connector types

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-ev-search",
    "arguments": {
      "query": "Tesla Supercharger",
      "lat": 52.3676,
      "lon": 4.9041,
      "connectorTypes": ["Tesla"]
    }
  }
}

### Response
#### Success Response (200)
- **results** (array) - List of charging stations including address, connector types, and real-time availability.
```

--------------------------------

### POST /mcp (tomtom-dynamic-map)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Renders a dynamic map with overlays including markers, polygons, and route plans.

```APIDOC
## POST /mcp (tomtom-dynamic-map)

### Description
Render custom map images with markers, routes, polygons, and area overlays using server-side rendering. Supports both drawn lines and calculated road-following routes.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **params.arguments.markers** (array) - Optional - List of marker objects
- **params.arguments.polygons** (array) - Optional - List of polygon definitions
- **params.arguments.routePlans** (array) - Optional - List of route definitions

### Response
#### Success Response (200)
- **image** (string) - Base64-encoded PNG image
- **viz_id** (string) - ID for interactive UI elements
```

--------------------------------

### Deploy TomTom MCP Server using Docker

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Deploys the TomTom MCP Server using Docker containers. Supports both the default TomTom Maps backend and the TomTom Orbis Maps backend with additional features.

```bash
# Run with TomTom Maps backend (default)
docker run -p 3000:3000 ghcr.io/tomtom-international/tomtom-mcp:latest

# Run with TomTom Orbis Maps backend
docker run -p 3000:3000 -e MAPS=tomtom-orbis-maps ghcr.io/tomtom-international/tomtom-mcp:latest
```

--------------------------------

### POST /mcp (tomtom-static-map)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Generates a static map image based on center coordinates, zoom level, and style preferences.

```APIDOC
## POST /mcp (tomtom-static-map)

### Description
Generate custom static map images with specified center coordinates, zoom levels, and style options. Returns a PNG or JPG image of the specified map area.

### Method
POST

### Endpoint
/mcp

### Parameters
#### Request Body
- **params.arguments.center** (object) - Required - {lat, lon}
- **params.arguments.zoom** (integer) - Required - Zoom level
- **params.arguments.width** (integer) - Required - Image width
- **params.arguments.height** (integer) - Required - Image height

### Response
#### Success Response (200)
- **image** (string) - Base64-encoded map image
```

--------------------------------

### Configure TomTom MCP Server for Claude Desktop

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Adds TomTom MCP server configuration to the Claude Desktop settings. This allows Claude Desktop to utilize the MCP server for location-based AI assistant features.

```json
{
  "mcpServers": {
    "tomtom-mcp": {
      "command": "npx",
      "args": ["-y", "@tomtom-org/tomtom-mcp@latest"],
      "env": {
        "TOMTOM_API_KEY": "<your_API_KEY>",
        "MAPS": "tomtom-orbis-maps"
      }
    }
  }
}
```

--------------------------------

### Visualize GeoJSON Data using TomTom MCP

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Demonstrates how to trigger the tomtom-data-viz tool via a JSON-RPC request. This tool supports various visualization layers like clusters and heatmaps on Orbis Maps.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'tomtom-maps-backend: tomtom-orbis-maps' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "tools/call",
    "params": {
      "name": "tomtom-data-viz",
      "arguments": {
        "data_url": "https://example.com/stores.geojson",
        "layers": [
          {
            "type": "clusters",
            "cluster_radius": 50,
            "label_property": "name"
          },
          {
            "type": "heatmap",
            "heatmap_intensity": 1.5,
            "heatmap_weight": "sales"
          }
        ],
        "title": "Store Locations",
        "show_ui": true
      }
    },
    "jsonrpc": "2.0",
    "id": 16
  }'
```

--------------------------------

### Plan EV Routes with Charging Stops (tomtom-ev-routing)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Plans long-distance electric vehicle routes, optimizing charging stops based on battery state, vehicle specs, and connector compatibility. Requires API key and specifies origin, destination, and charging parameters.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'tomtom-maps-backend: tomtom-orbis-maps' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-ev-routing", \
      "arguments": { \
        "origin": { "lat": 52.3676, "lon": 4.9041 }, \
        "destination": { "lat": 50.1109, "lon": 8.6821 }, \
        "currentChargePercent": 80, \
        "maxChargeKWH": 75, \
        "minChargeAtDestinationPercent": 20, \
        "minChargeAtChargingStopsPercent": 10, \
        "consumptionInKWH": [ \
          { "speedKMH": 50, "consumptionUnitsPer100KM": 12 }, \
          { "speedKMH": 100, "consumptionUnitsPer100KM": 18 }, \
          { "speedKMH": 130, "consumptionUnitsPer100KM": 24 } \
        ], \
        "routeType": "fast", \
        "traffic": "live", \
        "avoid": ["tollRoads"], \
        "show_ui": true \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 12 \
  }'
```

--------------------------------

### Routing and EV Services

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Tools for calculating routes, including multi-stop planning and specialized EV routing.

```APIDOC
## [TOOL] tomtom-routing

### Description
Calculates the optimal route between two points.

### Parameters
#### Request Body
- **origin** (string) - Required - Starting coordinates.
- **destination** (string) - Required - Ending coordinates.

---

## [TOOL] tomtom-ev-routing

### Description
Plans long-distance EV routes with automatic charging stop optimization.

### Parameters
#### Request Body
- **origin** (string) - Required - Starting coordinates.
- **destination** (string) - Required - Ending coordinates.
- **vehicle_profile** (object) - Required - EV battery and connector specifications.
```

--------------------------------

### Find EV Charging Stations (tomtom-ev-search)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Locates EV charging stations with real-time availability, connector types, and power levels. Supports filtering by query, location, radius, connector types, and minimum power. Returns detailed station information.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'tomtom-maps-backend: tomtom-orbis-maps' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-ev-search", \
      "arguments": { \
        "query": "Tesla Supercharger", \
        "lat": 52.3676, \
        "lon": 4.9041, \
        "radius": 10000, \
        "connectorTypes": ["IEC62196Type2CCS", "Tesla"], \
        "minPowerKW": 50, \
        "limit": 10, \
        "includeAvailability": true, \
        "show_ui": true \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 13 \
  }'
```

--------------------------------

### POST /mcp (tomtom-routing)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Calculates optimal routes between two locations.

```APIDOC
## POST /mcp (tomtom-routing)

### Description
Calculate optimal routes between two locations with turn-by-turn directions, distance, and travel time.

### Method
POST

### Request Body
- **params.arguments.origin** (object) - Required - {lat, lon}
- **params.arguments.destination** (object) - Required - {lat, lon}
- **params.arguments.travelMode** (string) - Optional - e.g., "car"

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-routing",
    "arguments": { "origin": {"lat": 52.3, "lon": 4.9}, "destination": {"lat": 52.0, "lon": 5.1} }
  }
}
```

--------------------------------

### POST /mcp (tomtom-fuzzy-search)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Performs a typo-tolerant search for addresses and points of interest.

```APIDOC
## POST /mcp (tomtom-fuzzy-search)

### Description
Typo-tolerant search for addresses, points of interest, and geographic entities. Ideal for user-facing search interfaces.

### Method
POST

### Endpoint
/mcp

### Request Body
- **method** (string) - Required - Must be "tools/call"
- **params.name** (string) - Required - Must be "tomtom-fuzzy-search"
- **params.arguments.query** (string) - Required - The search term
- **params.arguments.lat** (number) - Optional - Latitude for bias
- **params.arguments.lon** (number) - Optional - Longitude for bias
- **params.arguments.radius** (number) - Optional - Search radius in meters
- **params.arguments.limit** (number) - Optional - Max results

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-fuzzy-search",
    "arguments": { "query": "coffee shops", "lat": 40.78, "lon": -73.96 }
  }
}
```

--------------------------------

### POST /mcp (tomtom-nearby)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Discovers services and points of interest within a specified radius.

```APIDOC
## POST /mcp (tomtom-nearby)

### Description
Discover services and points of interest within a specified radius from a location, sorted by distance.

### Method
POST

### Request Body
- **params.arguments.lat** (number) - Required - Center latitude
- **params.arguments.lon** (number) - Required - Center longitude
- **params.arguments.radius** (number) - Required - Search radius in meters

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-nearby",
    "arguments": { "lat": 48.85, "lon": 2.29, "radius": 1000 }
  }
}
```

--------------------------------

### POST /mcp (tomtom-poi-search)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Finds specific business categories and points of interest using category IDs.

```APIDOC
## POST /mcp (tomtom-poi-search)

### Description
Find specific business categories and points of interest. Filter by category IDs for precise results.

### Method
POST

### Request Body
- **params.arguments.query** (string) - Required - POI name or category
- **params.arguments.categorySet** (string) - Optional - Category ID (e.g., 7315 for Restaurant)
- **params.arguments.countrySet** (string) - Optional - ISO country code

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-poi-search",
    "arguments": { "query": "IKEA", "categorySet": "7327" }
  }
}
```

--------------------------------

### Make HTTP Request to TomTom MCP Server

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Illustrates how to make a request to the TomTom MCP Server running in HTTP mode using curl. It includes setting the API key and content type, and sending a geocoding request.

```bash
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
}'
```

--------------------------------

### Enable TomTom Orbis Maps Backend

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

To enable TomTom Orbis Maps for all MCP tools, set the environment variable MAPS to 'tomtom-orbis-maps'. This configuration switch allows access to Orbis-exclusive tools in addition to the standard TomTom Maps tools.

```bash
export MAPS=tomtom-orbis-maps
```

--------------------------------

### Geocoding and Search Tools

Source: https://github.com/tomtom-international/tomtom-mcp/blob/main/README.md

Tools for converting addresses to coordinates and performing various types of location searches.

```APIDOC
## [TOOL] tomtom-geocode

### Description
Performs forward geocoding to convert a human-readable address into geographic coordinates.

### Parameters
#### Request Body
- **query** (string) - Required - The address or location name to geocode.

### Response
#### Success Response (200)
- **position** (object) - The latitude and longitude coordinates of the address.

---

## [TOOL] tomtom-fuzzy-search

### Description
Performs a general search with typo tolerance and suggestions for locations or POIs.

### Parameters
#### Request Body
- **query** (string) - Required - The search term.

### Response
#### Success Response (200)
- **results** (array) - A list of matching locations with details.
```

--------------------------------

### POST /mcp (tomtom-waypoint-routing)

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Plans multi-stop routes through three or more waypoints.

```APIDOC
## POST /mcp (tomtom-waypoint-routing)

### Description
Plan multi-stop routes through three or more waypoints in the exact sequence provided.

### Method
POST

### Request Body
- **params.arguments.waypoints** (array) - Required - List of {lat, lon} objects

### Request Example
{
  "method": "tools/call",
  "params": {
    "name": "tomtom-waypoint-routing",
    "arguments": { "waypoints": [{"lat": 52.3, "lon": 4.9}, {"lat": 52.4, "lon": 4.8}] }
  }
}
```

--------------------------------

### Fuzzy Search with TomTom MCP

Source: https://context7.com/tomtom-international/tomtom-mcp/llms.txt

Performs typo-tolerant searches for addresses, POIs, and geographic entities. Useful for user-facing search interfaces where input might be imprecise. Requires an API key and specifies search parameters like query, location, radius, and category.

```bash
curl --location 'http://localhost:3000/mcp' \
  --header 'tomtom-api-key: <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "method": "tools/call", \
    "params": { \
      "name": "tomtom-fuzzy-search", \
      "arguments": { \
        "query": "coffee shops near Central Park", \
        "lat": 40.7829, \
        "lon": -73.9654, \
        "radius": 2000, \
        "limit": 10, \
        "categorySet": "9376", \
        "typeahead": true \
      } \
    }, \
    "jsonrpc": "2.0", \
    "id": 3 \
  }'
```