Cursor Integration

November 5, 2025 ยท View on GitHub

This guide explains how to configure Cursor IDE for use with the Mapbox MCP DevKit Server.

Requirements

# from repository root:
# using node
npm run build

# or alternatively, using docker
docker build -t mapbox-mcp-devkit .

Setup Instructions

Configure Cursor to use Mapbox MCP DevKit Server

  1. Go to Cursor Settings/ MCP Tools and click on "Add Custom MCP".

  2. Add either of the following MCP config:

    • NPM version (recommended for simplicity)

      {
  "mcpServers": {
    "MapboxDevKit": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-devkit-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

    • Docker version (recommended for isolation)

      {
  "mcpServers": {
    "MapboxDevKit": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env",
        "MAPBOX_ACCESS_TOKEN=<YOUR_TOKEN>",
        "mapbox-mcp-devkit"
      ]
    }
  }
}

    • Node version (for local development)

      {
  "mcpServers": {
    "MapboxDevKit": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/repo/dist/esm/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

  3. Click "Save" to apply the configuration.

Important Notes

Token Scopes

Your Mapbox access token must have the appropriate scopes for the tools you want to use. See the main README for required token scopes per tool.

Configuration Options

Additional environment variables you can set:

  • OTEL_EXPORTER_OTLP_ENDPOINT - Enable OpenTelemetry tracing (see tracing docs)
  • OTEL_SERVICE_NAME - Override service name for tracing
  • MAPBOX_API_ENDPOINT - Override Mapbox API endpoint (advanced)

Troubleshooting

Server Not Appearing

If the Mapbox DevKit Server doesn't appear in Cursor's MCP tools:

  1. Check that your MAPBOX_ACCESS_TOKEN is valid
  2. For Docker: ensure the image is built with docker images | grep mapbox-mcp-devkit
  3. Check Cursor's logs for any error messages

Connection Errors

If you see JSON-RPC or parsing errors:

  1. If using Node version, verify the path to dist/esm/index.js is correct
  2. Run npm run build to ensure the latest build is available

Tool Execution Failures

If tools fail to execute:

  1. Verify your Mapbox token has the required scopes (see README)
  2. Check if you're hitting rate limits (429 errors)
  3. Enable verbose errors by adding "VERBOSE_ERRORS": "true" to the env config

Example Usage

Once configured, you can use natural language to interact with Mapbox tools:

  • "List all my Mapbox styles"
  • "Show me the bounding box for San Francisco"
  • "Convert these coordinates to lat/lng: -122.4194, 37.7749"
  • "Create a new Mapbox style called 'my-custom-map'"

See the README for more example prompts.