Claude Desktop Integration Guide

November 5, 2025 · View on GitHub

This guide shows how to integrate the Mapbox MCP DevKit Server with Claude Desktop for enhanced development workflows.

Prerequisites

Claude Desktop application installed
A Mapbox account with an access token
Node.js 22 or higher (for local development)

Installation

Get Your Mapbox Access Token

Sign up for a free Mapbox account at mapbox.com/signup
Navigate to your Account page
Create a new token with the required scopes for your use case

For more information about Mapbox access tokens, see the Mapbox documentation on access tokens.

⚠️ CRITICAL: Token Scopes Required

Each Mapbox tool requires specific token scopes/privileges to function. Using a token without the correct scope will result in authentication errors. Before using any tool, ensure your token has the required scopes:

Style operations: Require styles:read, styles:write, styles:list, or styles:download scopes
Token management: Requires tokens:read and tokens:write scopes
Style previews: Require tokens:read scope and at least one public token with styles:read scope

See the Token Requirements section below for detailed scope information for each tool.

Configuration

Install Claude Desktop

Download and install the Claude Desktop application from the official page.

Configure Claude Desktop

Option 1: DXT Package Installation (Recommended)

The easiest way to install this MCP server is using the pre-built DXT package:

⚠️ Important: Make sure you have the latest version of Claude Desktop installed. DXT support requires recent versions of Claude Desktop to function properly.

📦 Download DXT Package

Installation Steps

Update Claude Desktop - Download the latest version if you haven't recently
Download the .dxt file from the link above
Open the file with Claude Desktop
Follow the installation prompts
Provide your Mapbox access token when prompted

This method automatically handles the configuration and setup, providing a one-click installation experience.

Option 2: Manual Configuration

For users who prefer manual configuration or need custom setups, you can configure the server directly:

Open Claude Desktop settings
Navigate to the Model Context Protocol section
Modify claude_desktop_config.json to add the new server:

NPM Package

{
  "mcpServers": {
    "mapbox-devkit": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-devkit-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Docker Runtime

{
  "mcpServers": {
    "mapbox-devkit": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MAPBOX_ACCESS_TOKEN=your_token_here",
        "mapbox-mcp-devkit"
      ]
    }
  }
}

Local Development

If you want to use a local version (need to clone and build from this repo):

{
  "mcpServers": {
    "mapbox-devkit": {
      "command": "node",
      "args": ["/absolute/path/to/mapbox-mcp-devkit/dist/esm/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

⚠️ Important: Make sure you have the latest version of Claude Desktop installed. DXT support requires recent versions of Claude Desktop to function properly.

Usage Examples

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

Style Management

"List all my Mapbox styles"
"Create a new style called 'Dark Mode' with a basic dark theme"
"Update the style with ID 'xyz' to change the water color to blue"
"Generate a preview URL for my style"

Token Management

"Create a new token for my web app with styles:read and fonts:read permissions"
"List all my public tokens"
"Show me my default public token"

GeoJSON Processing

"Calculate the bounding box of this GeoJSON data"
"Generate a preview URL for this GeoJSON file"
"Convert coordinates from WGS84 to Web Mercator"

Token not found error:
- Verify your MAPBOX_ACCESS_TOKEN is set correctly in the configuration
- Check that the token has the required scopes for the operation
Server connection issues:
- Ensure Node.js version is 22 or higher (for NPM package option)
- Check your internet connection for npm package downloads
- Restart Claude Desktop after configuration changes
Permission errors:
- Verify your token has the correct scopes (see main README for scope requirements)
- Some operations require secret tokens (starting with sk.)

Debug Mode

Enable verbose error reporting by adding the environment variable:

{
  "mcpServers": {
    "mapbox-devkit": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-devkit-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your_token_here",
        "VERBOSE_ERRORS": "true"
      }
    }
  }
}

This will provide detailed error messages to help diagnose issues.

Token Requirements

⚠️ Each tool requires specific token scopes. Authentication will fail if your token lacks the required privileges.

Different tools require different scopes:

Style Tools

List styles: styles:list scope
Create/Update styles: styles:write scope
Retrieve styles: styles:download scope
Delete styles: styles:write scope
Preview styles: tokens:read scope and at least one public token with styles:read scope

Token Management Tools

List tokens: tokens:read scope
Create tokens: tokens:write scope

Local Processing Tools

These tools work locally and don't require specific token scopes:

Bounding box calculation
GeoJSON preview generation
Coordinate conversion

Best Practices

Token Security:
- Use environment variables for tokens
- Create restricted tokens for specific domains
- Regularly rotate tokens used in production
Development Workflow:
- Use the NPM package for consistent updates
- Enable verbose errors during development
- Test with different token scopes for your use case
Performance:
- Use appropriate pagination for large datasets
- Cache frequently accessed styles and tokens
- Consider using Docker for consistent environments across team members