DevKit MCP Server | API Docs

The Mapbox DevKit MCP Server provides AI assistants with direct access to Mapbox developer APIs, documentation, and other helpful developer tools through the Model Context Protocol. This server helps developers build Mapbox applications more efficiently by enabling conversational interactions with style management, token creation, documentation access, and more.

Installation

Requirements:

Node.js LTS or later is required to build and run the DevKit MCP Server.

A Mapbox Access Token is required

You will need a Mapbox Access Token with appropriate scopes to use the DevKit MCP Server. An access token associates your use of Mapbox Services with your account. If you don't have one, you can create a free account, then copy your access token from the Access Tokens page.

Use the Mapbox DevKit MCP Server

The Mapbox DevKit MCP Server can be used in several ways:

Option 1: Hosted Endpoint
Option 2: Quick Start with npm
Option 3: Local Deployment

Hosted Endpoint

For the simplest setup, you can connect directly to Mapbox's hosted DevKit MCP endpoint without installing or running anything locally. This endpoint is available at https://mcp-devkit.mapbox.com/mcp.

When you first connect, you will be prompted to complete an OAuth authentication flow through your browser before the MCP server becomes available. This hosted option eliminates the need for managing access tokens manually and is ideal for quick setup and testing.

Hosted endpoint limitations

The create-token tool and MCP Prompts are not available on the hosted endpoint. Use the npm or local setup to access these features.

Configure your AI assistant to use the hosted endpoint:

claude_desktop_config.json


{
  "mcpServers": {
    "mapbox-devkit-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-devkit.mapbox.com/mcp"
      ]
    }
  }
}

mcp.json


{
  "servers": {
    "mapbox-devkit-mcp": {
      "type": "http",
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

mcp.json


{
  "mcpServers": {
    "mapbox-devkit-mcp": {
      "type": "http",
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

Quick Start with `npm`

You must configure consuming applications to connect to the Mapbox DevKit MCP Server. This typically involves referencing the MCP Server's NPM package via npx and setting your Mapbox Access Token as an environment variable.

Configure your AI assistant to use the Mapbox DevKit MCP Server via npm:

claude_desktop_config.json


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

mcp.json


{
  "servers": {
    "MapboxDevKitServer": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@mapbox/mcp-devkit-server"
      ],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

mcp.json


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


$claude mcp add --transport stdio MapboxDevKitServer -- npx -y @mapbox/mcp-devkit-server

# Set the required environment variable:
$export MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN


$codex mcp add MapboxDevKitServer --env MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN -- npx -y @mapbox/mcp-devkit-server

Note

If you use a Node version manager like fnm or nvm to manage multiple versions of Node.js, Claude may not automatically resolve the correct version when launching the MCP Server via npx.

To make sure the server runs using the same Node.js version as npx, you should explicitly specify the full path to the node executable in the command field.

First, find your Node.js installation path by running this in your terminal (after activating your desired Node version):

On macOS/Linux:


which node
which npx

On Windows (PowerShell):


(Get-Command node).Path
(Get-Command npx).Path

On Windows (Command Prompt):


where node
where npx

Then use those paths in your configuration. For example:


{
  "mcpServers": {
    "MapboxDevKitServer": {
      "command": "/Users/your-username/.local/state/fnm_multishells/12345_1234567890123/bin/node",
      "args": ["/Users/your-username/.npm/_npx/1234567890/node_modules/.bin/npx", "-y", "@mapbox/mcp-devkit-server"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

Note

The exact paths will vary depending on your system and version manager. Use the output from which node and which npx to find your actual paths.

Consult the documentation of your AI model or application for specific instructions on how to configure MCP servers.

Installation guides are available for the following applications in the public repository:

Local Deployment

To use Mapbox DevKit MCP Server with local Node.js involves two main steps:

Clone the MCP Server code repository and build the project.
Configure a consuming application to run and connect to the MCP Server, providing your Mapbox Access Token.

Clone and build the DevKit MCP Server

Clone the repository:


$git clone https://github.com/mapbox/mcp-devkit-server.git

Change into the project directory:


$cd mcp-devkit-server

Install dependencies:


$npm install

Build the project:


$npm run build

The built DevKit MCP Server will be located in the dist directory in two formats:

dist/esm/index.js for ESM (ECMAScript Module) support
dist/commonjs/index.js for CommonJS support

You will need to reference one of these locations when configuring consuming applications. Use the ESM version unless you have specific CommonJS requirements.

Docker Configuration

You may also build and run the DevKit MCP Server using Docker. See the Dockerfile in the project repository.

Configure the consuming application

You must configure consuming applications to connect to the Mapbox DevKit MCP Server. This typically involves specifying the path to the MCP Server node.js file and providing your Mapbox Access Token as an environment variable.

Configure your AI assistant to use the local DevKit MCP Server build:

claude_desktop_config.json


{
  "mcpServers": {
    "MapboxDevKitServer": {
      "command": "node",
      "args": [
        "/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"
      ],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

mcp.json


{
  "servers": {
    "MapboxDevKitServer": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"
      ],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}

mcp.json


{
  "mcpServers": {
    "MapboxDevKitServer": {
      "command": "node",
      "args": [
        "/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"
      ],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"
      }
    }
  }
}


$claude mcp add --transport stdio MapboxDevKitServer -- node /Users/username/github-projects/mcp-devkit-server/dist/esm/index.js

# Set the required environment variable:
$export MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN


$codex mcp add MapboxDevKitServer --env MAPBOX_ACCESS_TOKEN=YOUR_MAPBOX_ACCESS_TOKEN -- node /Users/username/github-projects/mcp-devkit-server/dist/esm/index.js

Consult the documentation of your AI model or application for specific instructions on how to configure MCP servers.

Installation guides are available for the following applications in the public repository:

Configuration

The Mapbox DevKit MCP Server supports several configuration options to customize its behavior.

Environment Variables

MAPBOX_ACCESS_TOKEN (required): Your Mapbox access token for authenticating API requests. Different tools require different token scopes.
VERBOSE_ERRORS (optional): Enable enhanced error messaging for debugging purposes.
ENABLE_MCP_UI (optional): Toggle interactive iframe embedding for capable clients. Defaults to true. Set to false to disable.
CLIENT_NEEDS_RESOURCE_FALLBACK (optional): Enable fallback tools for clients that don't support native MCP resources. Defaults to false. Set to true to enable.

OpenTelemetry Configuration

The DevKit MCP Server supports distributed tracing via OpenTelemetry for observability:

OTEL_EXPORTER_OTLP_ENDPOINT (optional): OTLP endpoint URL to enable tracing (e.g., http://localhost:4318).
OTEL_SERVICE_NAME (optional): Service identification name. Defaults to mapbox-mcp-devkit-server.
OTEL_TRACES_SAMPLER_ARG (optional): Sampling rate from 0.0 to 1.0 (e.g., 0.1 for 10% sampling).

Token Scope Requirements

Different tools in the DevKit MCP Server require specific token scopes:

Style operations: styles:list, styles:read, styles:download, styles:write
Token management: tokens:read, tokens:write (the create-token tool requires tokens:write and is only available when running locally via npm or local deployment — it is not available on the hosted endpoint)
Feedback access: user-feedback:read
Preview generation: tokens:read and at least one public token with styles:read

You can configure these scopes when creating your access token on the Access Tokens page.

Resources

The Mapbox DevKit MCP Server provides access to static reference data through MCP Resources. Clients can access these resources using the following URIs:

resource://mapbox-style-layers - Layer types, paint and layout properties reference
resource://mapbox-streets-v8-fields - Streets v8 source layer field definitions with enumerated values
resource://mapbox-token-scopes - Token scope documentation and valid scope combinations
resource://mapbox-layer-type-mapping - Streets v8 source layer to GL JS layer type compatibility matrix

These resources provide comprehensive reference materials to help you understand Mapbox APIs, build applications more effectively, and work with style specifications.

Tools

The Mapbox DevKit MCP Server provides the following tools for managing Mapbox resources and accessing developer APIs. Tools are organized by category based on their functionality.

Documentation tools have moved

Documentation search and retrieval tools that were in the DevKit MCP Server before have moved to the dedicated Mapbox Docs MCP Server (@mapbox/mcp-docs-server), which provides full-text search across all Mapbox documentation and does not require a Mapbox access token.

Style Management Tools

Tool	Description
`ListStylesTool`	Lists all styles associated with your Mapbox account with pagination support. Powered by the Styles API.
`CreateStyleTool`	Creates a new Mapbox style with specified properties. Powered by the Styles API.
`RetrieveStyleTool`	Retrieves an existing Mapbox style by ID. Powered by the Styles API.
`UpdateStyleTool`	Changes an existing Mapbox style with new properties. Powered by the Styles API.
`DeleteStyleTool`	Deletes a Mapbox style by ID. Powered by the Styles API.
`PreviewStyleTool`	Generates shareable preview URLs for Mapbox styles with customizable map parameters (center, zoom, bearing, pitch).
`ValidateStyleTool`	Performs offline JSON validation of style specifications against Mapbox schema requirements.
`StyleBuilderTool`	Conversational style builder that helps create and change Mapbox styles through natural language interactions.
`style_comparison_tool`	Generates a side-by-side comparison URL for two Mapbox styles. Useful for reviewing differences before and after style changes. Powered by the Styles API.

Token Management Tools

Tool	Description
`create-token`	Creates a new Mapbox access token with specified scopes, optional URL restrictions, and 1-hour expiration windows. Powered by the Tokens API.
`list-tokens`	Lists all access tokens for your account with filtering by type, creation date, and modification status. Auto-pagination available. Powered by the Tokens API.

Tileset Tools

Tool	Description
`tilequery_tool`	Queries vector and raster data from Mapbox tilesets at a geographic coordinate. Powered by the Tilequery API.

Feedback Tools

Tool	Description
`list_feedback_tool`	Filters user-reported map data issues by status, category, dates, and trace IDs with full sorting and pagination. Powered by the Feedback API.
`get_feedback_tool`	Retrieves individual user feedback items by UUID. Powered by the Feedback API.

Local Processing Tools

These tools do operations locally without requiring API calls:

Tool	Description
`GeoJSON Validation`	Checks GeoJSON structure, coordinates, geometry types, ring closure, and position validity.
`GeoJSON Preview`	Generates geojson.io visualization URLs (optimized for small-to-medium files).
`Validate Expression Tool`	Tests Mapbox style expressions for syntax, operators, and argument correctness. Supports 20+ operator categories.
`ConvertCoordinatesTool`	Transforms coordinates between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857) projection systems.
`CalculateBoundingBoxTool`	Calculates extent [minX, minY, maxX, maxY] from GeoJSON features.
`Color Contrast Checker`	Validates WCAG 2.1 AA/AAA compliance between text and background colors. Supports hex, RGB, and named color formats.
`compare_styles_tool`	Deep comparison of two styles identifying additions, removals, and modifications with JSON path reporting.
`Style Optimization Tool`	Removes unused sources, duplicate layers, simplifies expressions, and eliminates empty layers with file size metrics.
`country_bounding_box_tool`	Returns the bounding box `[minX, minY, maxX, maxY]` for a country by its ISO 3166-1 country code.

MCP Prompts

MCP Prompts are pre-built workflow templates that orchestrate multiple tools to do complex tasks. These prompts guide you through multi-step processes with structured interactions. MCP Prompts are available when running the server locally via npm or local deployment; they are not available on the hosted endpoint.

Available Prompts

`create-and-preview-style`

Orchestrates style creation with automatic token management and preview URL generation. Walks you through creating a new style and generating a shareable preview link.

`build-custom-map`

Accepts theme descriptions (e.g., "dark cyberpunk") and uses the Style Builder for conversational map creation with automatic preview generation.

`analyze-geojson`

Validates GeoJSON data, calculates bounding boxes, provides coordinate conversions, and generates visualization links for comprehensive GeoJSON analysis.

`setup-mapbox-project`

Complete project initialization including creation of development and production tokens with domain restrictions, initial styles, and integration guidance.

`debug-mapbox-integration`

Systematic troubleshooting workflow that verifies token validity, scopes, style existence, and API connectivity with step-by-step fix recommendations.

`design-data-driven-style`

Creates styles with dynamic data visualization using expressions. Offers color scales and zoom-based conditional logic templates for data-driven mapping.

`prepare-style-for-production`

Comprehensive validation combining expression checking, coordinate validation, color contrast analysis, optimization, and deployment readiness assessment.

Agent Skills

Agent Skills are pre-built knowledge modules that complement the DevKit MCP Server tools with best practices and domain knowledge. These skills can be installed to enhance AI assistant capabilities with Mapbox-specific knowledge.

Available Skills

`mapbox-cartography`

Design principles, color theory, visual hierarchy, and typography guidance for creating effective and beautiful maps.

`mapbox-token-security`

Token management best practices, rotation strategies, scope configurations, and security recommendations for production deployments.

`mapbox-style-patterns`

Common style configurations for typical use cases including basemaps, data visualization, custom themes, and specialized mapping applications.

`mapbox-integration-patterns`

Framework-specific integration guidance for React, Vue, Angular, Svelte, and vanilla JavaScript with code examples and best practices.

`mapbox-style-quality`

Validation, optimization, accessibility guidance, and quality assurance practices for production-ready map styles.

Installing Skills

Skills can be installed locally for Claude Code or globally for other applications:

Claude Code (project-specific):


mkdir -p .claude && ln -s ../skills .claude/skills

Global installation:


cp -r skills/* ~/.claude/skills/

Observability

The Mapbox DevKit MCP Server includes built-in OpenTelemetry instrumentation for comprehensive observability and distributed tracing.

Features

Tool Run Tracing: Timing, success and error status, and performance metrics for all tool invocations
HTTP Request Tracing: API call tracking with CloudFlight correlation IDs and network performance data
Configuration Analysis: Loading and validation tracking for environment variables and settings
Low Overhead: Less than 1% CPU impact and approximately 10MB memory overhead

Supported Backends

The server supports any OTLP-compatible tracing backend, including:

Jaeger
Zipkin
Datadog
New Relic
Honeycomb
AWS X-Ray
Azure Monitor
Google Cloud Trace

Quick Start with Jaeger

For local development and testing:


# Start Jaeger in Docker
npm run tracing:jaeger:start

# Configure OTEL_EXPORTER_OTLP_ENDPOINT in .env file
# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Run the server
npm run inspect:build

# View traces at http://localhost:16686

Configuration

Set these environment variables to enable tracing:

OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL (e.g., http://localhost:4318)
OTEL_SERVICE_NAME: Service identification (default: mapbox-mcp-devkit-server)
OTEL_TRACES_SAMPLER_ARG: Sampling rate from 0.0 to 1.0 (e.g., 0.1 for 10% sampling)

このpageは役に立ちましたか？

Mapbox DevKit MCP Server

Installation​

Use the Mapbox DevKit MCP Server​

Hosted Endpoint​

Quick Start with npm​

Local Deployment​

Clone and build the DevKit MCP Server​

Configure the consuming application​

Configuration​

Environment Variables​

OpenTelemetry Configuration​

Token Scope Requirements​

Resources​

Tools​

Style Management Tools​

Token Management Tools​

Tileset Tools​

Feedback Tools​

Local Processing Tools​

MCP Prompts​

Available Prompts​

create-and-preview-style​

build-custom-map​

analyze-geojson​

setup-mapbox-project​

debug-mapbox-integration​

design-data-driven-style​

prepare-style-for-production​

Agent Skills​

Available Skills​

mapbox-cartography​

mapbox-token-security​

mapbox-style-patterns​

mapbox-integration-patterns​

mapbox-style-quality​

Installing Skills​

Observability​

Features​

Supported Backends​

Quick Start with Jaeger​

Configuration​

Installation

Use the Mapbox DevKit MCP Server

Hosted Endpoint

Quick Start with `npm`

Local Deployment

Clone and build the DevKit MCP Server

Configure the consuming application

Configuration

Environment Variables

OpenTelemetry Configuration

Token Scope Requirements

Resources

Tools

Style Management Tools

Token Management Tools

Tileset Tools

Feedback Tools

Local Processing Tools

MCP Prompts

Available Prompts

`create-and-preview-style`

`build-custom-map`

`analyze-geojson`

`setup-mapbox-project`

`debug-mapbox-integration`

`design-data-driven-style`

`prepare-style-for-production`

Agent Skills

Available Skills

`mapbox-cartography`

`mapbox-token-security`

`mapbox-style-patterns`

`mapbox-integration-patterns`

`mapbox-style-quality`

Installing Skills

Observability

Features

Supported Backends

Quick Start with Jaeger

Configuration