Quick Setup

Quick Setup

Prerequisites

Before you begin, ensure you have:

• Node.js 22.9.0 or higher installed (download)
• A TomTom MOVE Portal API key from move.tomtom.com/register (includes a 30-day free trial). The trial comes with pre-configured sample junctions and routes so you can start querying immediately.
• Optionally, a TomTom Developer API key from developer.tomtom.com (required for live traffic tools; these work with any location, no preconfiguration needed)
• An MCP-compatible AI client (Claude Desktop, VS Code with GitHub Copilot, etc.)

Choose Your Client

Each integration guide has the exact config format and file path for that client:

• Claude Desktop
• VS Code with GitHub Copilot

Using a different MCP client? Most clients accept the standard MCP server format. Point yours at the command npx -y @tomtom-org/tomtom-traffic-analytics-mcp@latest with TOMTOM_MOVE_PORTAL_KEY (required) and TOMTOM_API_KEY (optional) in the environment. The Claude Desktop guide above is a good template to adapt.

HTTP Transport

HTTP mode runs the server as a standalone process that listens on a local port. This is useful for clients that support HTTP-based MCP or for sharing a single server across multiple clients.

The HTTP binary is bundled inside the main package. Install the package first, then start the server:

1# Install the package
2npm install @tomtom-org/tomtom-traffic-analytics-mcp@latest
3
4# Set your API keys
5export TOMTOM_MOVE_PORTAL_KEY=your_key
6export TOMTOM_API_KEY=your_key
7
8# Start the HTTP server
9npx tomtom-traffic-analytics-mcp-http

The server listens on http://localhost:3000/mcp by default. You can verify it is running with the health endpoint:

curl http://localhost:3000/health

Configure your client to connect:

1{
2  "mcpServers": {
3    "tomtom-traffic-analytics": {
4      "type": "http",
5      "url": "http://localhost:3000/mcp"
6    }
7  }
8}

HTTP configuration options:

In HTTP mode, API keys can also be passed per-request as HTTP headers (tomtom-move-portal-key and tomtom-api-key). Headers take precedence over environment variables.

Which API Key Do I Need?

Do I Need to Set Up Data in MOVE Portal First?

Live Traffic (flow, incidents) uses the public TomTom Developer Portal. It works immediately on any coordinates or bounding box, no pre-configuration required.

Area Analytics needs a MOVE Portal key, but no portal-side setup. Supply any GeoJSON polygon at query time.

Junction Analytics and Route Monitoring operate on junctions and routes that you create in MOVE Portal. The MCP queries them by their MOVE-assigned IDs, so tomtom-junction-search and tomtom-route-search return empty lists until you configure at least one junction or route in the portal UI. See the API Access and Data Setup overview for details.

Running Alongside TomTom MCP Server

This server focuses on traffic analytics: congestion, delays, incidents, and historical trends. For geocoding, routing, search, and map rendering, use the companion TomTom MCP Server. The two servers complement each other and can run side-by-side in any MCP client.

Example configuration with both servers:

1{
2  "mcpServers": {
3    "tomtom-traffic-analytics": {
4      "command": "npx",
5      "args": ["-y", "@tomtom-org/tomtom-traffic-analytics-mcp@latest"],
6      "env": {
7        "TOMTOM_MOVE_PORTAL_KEY": "your_move_portal_key",
8        "TOMTOM_API_KEY": "your_tomtom_developer_key"
9      }
10    },
11    "tomtom-mcp": {
12      "command": "npx",
13      "args": ["-y", "@tomtom-org/tomtom-mcp"],
14      "env": {
15        "TOMTOM_API_KEY": "your_tomtom_developer_key"
16      }
17    }
18  }
19}

Common Issues

Next Steps

• SQL Filtering: Understand how every tool uses SQL to filter and aggregate data
• Available Tools: Browse all 8 tools with parameters and SQL table references
• Use Cases: See example workflows and prompts