TomTom Traffic Analytics MCP Server

MCP server for TomTom Traffic Analytics APIs — enabling AI assistants to access real-time and historical traffic data for area analysis, junction monitoring, route tracking, and live traffic insights.

Tip: Pair with TomTom MCP Server for geocoding, routing, and mapping capabilities.

API Access Requirements

This MCP server connects to multiple TomTom APIs with different access requirements:

| API Category | Environment Variable | Access | |--------------|---------------------|--------| | MOVE Portal | TOMTOM_MOVE_PORTAL_KEY | Sign up for MOVE (30-day free trial) | | TomTom Developer | TOMTOM_API_KEY | TomTom Developer Portal |

Which API is used by each tool?

| Tools | API Required | |-------|--------------| | Area Analytics (1 tool) | MOVE Portal | | Junction Analytics (3 tools) | MOVE Portal | | Route Monitoring (2 tools) | MOVE Portal | | Live Traffic (2 tools) | TomTom Developer |

Recommended agent workflow

1. Junction analysis: tomtom-junction-search (find IDs by name/status/country) → tomtom-junction-live-data or tomtom-junction-archive (traffic analysis)
2. Route analysis: tomtom-route-search (find IDs by name/status/delay) → tomtom-route-monitoring-details (segment-level analysis)

Quick Start

Prerequisites

• Node.js 22+
• API keys (see table above)

Install from npm

npm install @tomtom-org/tomtom-traffic-analytics-mcp

Or run directly with npx:

npx @tomtom-org/tomtom-traffic-analytics-mcp

Install from source

git clone https://github.com/tomtom-international/tomtom-traffic-analytics-mcp.git
cd tomtom-traffic-analytics-mcp
npm install
npm run build

Configuration

# Create .env file
echo "TOMTOM_MOVE_PORTAL_KEY=your_move_portal_key" > .env
echo "TOMTOM_API_KEY=your_tomtom_developer_key" >> .env

Run

node ./bin/tomtom-traffic-analytics-mcp.js

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "tomtom-traffic-analytics": {
      "command": "npx",
      "args": ["-y", "@tomtom-org/tomtom-traffic-analytics-mcp"],
      "env": {
        "TOMTOM_MOVE_PORTAL_KEY": "your_move_portal_key",
        "TOMTOM_API_KEY": "your_tomtom_developer_key",
        "USE_STDIO": "true"
      }
    }
  }
}

SQL Filtering

Analytical tools return large datasets that can overflow LLM context windows. To address this, all analytical tools require a sql_queries parameter that filters/aggregates data server-side using DuckDB.

All tools require sql_queries:

• tomtom-junction-search, tomtom-junction-live-data, tomtom-junction-archive
• tomtom-route-search, tomtom-route-monitoring-details
• tomtom-area-analytics-stats
• tomtom-traffic-flow-segment, tomtom-traffic-incidents

Example:

{
  "junctionIds": ["abc-123"],
  "sql_queries": {
    "top_delays": "SELECT approach_id, delay_sec FROM approaches ORDER BY delay_sec DESC LIMIT 5"
  }
}

See tool descriptions for available tables and columns.

Available Tools

Area Analytics (1 tool) — MOVE Portal

Analyze traffic patterns in custom geographical areas.

| Tool | Description | |------|-------------| | tomtom-area-analytics-stats | Direct statistics (requires sql_queries) |

Junction Analytics (3 tools) — MOVE Portal

Monitor traffic at intersections with real-time and historical data.

| Tool | Description | |------|-------------| | tomtom-junction-search | Search/filter all junctions via SQL (requires sql_queries) | | tomtom-junction-live-data | Real-time metrics (requires sql_queries) | | tomtom-junction-archive | Historical data (requires sql_queries) |

Route Monitoring (2 tools) — MOVE Portal

Track real-time traffic on strategic corridors.

| Tool | Description | |------|-------------| | tomtom-route-search | Search/filter all routes via SQL (requires sql_queries) | | tomtom-route-monitoring-details | Segment-level analysis (requires sql_queries) |

Live Traffic (2 tools) — TomTom Developer

Real-time traffic data for specific locations.

| Tool | Description | |------|-------------| | tomtom-traffic-flow-segment | Traffic for road segment at coordinates (requires sql_queries) | | tomtom-traffic-incidents | Traffic incidents in an area (requires sql_queries) |

Sample Prompts

• "Analyze traffic congestion in downtown Amsterdam for morning rush hours last week"
• "Compare traffic incidents between downtown and the airport area"
• "Show me the delay trends for junction abc-123 over the past two days"
• "Get current traffic conditions at coordinates 52.41, 4.84"

Development

Project Structure

src/
├── index.ts                 # Entry point
├── createServer.ts          # MCP server setup
├── tools/                   # MCP tool definitions
├── handlers/                # Request handlers
├── services/                # TomTom API clients
├── schemas/                 # Zod validation schemas
├── sql/                     # SQL filtering engine
│   ├── SqlFilterEngine.ts   # DuckDB engine
│   ├── flatteners/          # JSON → table converters
│   └── schemas/             # Table definitions
├── types/                   # TypeScript types
└── utils/                   # Logger & error handling

Commands

npm run build          # Build TypeScript
npm test               # Run unit tests
npm run test:all       # Run all tests (requires API key)
npm run lint           # Lint code

Unit tests run without API keys. Integration tests (npm run test:all) require valid API keys in .env.

Contributing

See CONTRIBUTING.md for development setup, coding guidelines, and how to submit pull requests.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Troubleshooting

| Issue | Solution | |-------|----------| | API key not found | Verify .env file exists with required keys | | Build errors | Run npm run build and check TypeScript errors | | Test failures | Ensure valid API key and check API quota |