cursor-setup.md

Cursor Integration Guide

This guide explains how to configure Cursor to use the TomTom MCP Server for location-based queries.

Prerequisites

• Cursor installed
• Node.js 22+ (For STDIO)
• Docker Setup Required (For HTTP)
• A valid TomTom API key

Setup

1. Navigate to Cursor Settings > Tools & Integrations, then click Add Custom MCP and add the following configuration:

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

Tip: To use the TomTom Orbis Maps backend (which includes additional tools like EV routing, search along route, and data visualization), add "MAPS": "tomtom-orbis-maps" to the env block above. See Available Tools for details.

Alternative Setup: HTTP Mode

You can also run TomTom MCP in HTTP mode separately and connect to it from Cursor:

1. Run TomTom MCP in HTTP mode:

   Using Docker

   # 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

2. Configure Cursor to connect to the HTTP server: Navigate to Cursor Settings > Tools & Integrations, then click Add Custom MCP and add the following configuration:

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

   Tip: Set the tomtom-maps-backend header to tomtom-orbis-maps to use the Orbis Maps backend (which includes additional tools like EV routing, search along route, and data visualization). This header is only used when the server is started without the MAPS env var (dual-backend mode).

3. You can see the TomTom MCP tools in Cursor tools menu.

Troubleshooting

• Ensure TOMTOM_API_KEY is valid and active
• Check that the MCP server is running
• Review logs for connection errors
• For HTTP mode, verify your connection URL and port are correct
• When using Docker, make sure the container is running with docker ps