Mapbox Developer MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with direct access to Mapbox developer APIs. This server enables AI models to interact with Mapbox services, helping developers build Mapbox applications more efficiently.

Looking for Mapbox documentation access? Use mcp-docs-server alongside this server — it provides AI assistants with access to Mapbox documentation, guides, and API references from docs.mapbox.com.

https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6

Table of Contents

• Mapbox Developer MCP Server
  • Table of Contents
  • Quick Start
    • Integration with Developer Tools
    • DXT Package Distribution
      • Creating the DXT Package
    • Hosted MCP Endpoint
    • Getting Your Mapbox Access Token
  • Tools
    • Reference Tools
    • Style Management Tools
    • Token Management Tools
      • create-token
      • list-tokens
    • Feedback Tools
    • Local Processing Tools
      • GeoJSON Preview tool (Beta)
      • Coordinate Conversion tool
      • Bounding Box tool
      • compare_styles_tool
      • Style Optimization tool
  • Resources
  • Observability & Tracing
    • Features
    • Quick Start with Jaeger
    • Supported Backends
    • Documentation
    • Environment Variables
  • Development
    • Testing
      • Tool Snapshot Tests
    • Inspecting Server
      • Using Node.js
      • Using Docker
    • Creating New Tools
    • Environment Variables
      • VERBOSE_ERRORS
  • Troubleshooting
  • Release Process
  • Contributing

Quick Start

Integration with Developer Tools

Get started by integrating with your preferred AI development environment:

• Claude Code Integration - Command-line development with Claude
• Claude Desktop Integration - Desktop application integration
• Cursor Integration - Cursor IDE integration
• VS Code Integration - Visual Studio Code with GitHub Copilot

DXT Package Distribution

This MCP server can be packaged as a DXT (Desktop Extension) file for easy distribution and installation. DXT is a standardized format for distributing local MCP servers, similar to browser extensions.

Creating the DXT Package

To create a DXT package:

# Install the DXT CLI tool
npm install -g @anthropic-ai/dxt

# Build the server first
npm run build

# Create the DXT package
npx @anthropic-ai/dxt pack

This will generate mcp-devkit-server.dxt using the configuration in manifest.json.

The DXT package includes:

• Pre-built server code (dist/esm/index.js)
• Server metadata and configuration
• User configuration schema for the Mapbox access token
• Automatic environment variable setup

Hosted MCP Endpoint

For quick access, you can use our hosted MCP endpoint:

Endpoint: https://mcp-devkit.mapbox.com/mcp

For detailed setup instructions for different clients and API usage, see the Hosted MCP Server Guide. Note: This guide references the standard MCP endpoint - you'll need to update the endpoint URL to use the devkit endpoint above.

Getting Your Mapbox Access Token

A Mapbox access token is required to use this MCP server.

1. Sign up for a free Mapbox account at mapbox.com/signup
2. Navigate to your Account page
3. 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.

⚠️ IMPORTANT: Token Privileges Required

The MAPBOX_ACCESS_TOKEN environment variable is required. Each tool requires specific token scopes/privileges to function properly. For example:

• Reading styles requires styles:read scope
• Creating styles requires styles:write scope
• Managing tokens requires tokens:read and tokens:write scopes
• Accessing feedback requires user-feedback:read scope

Tools

Reference Tools

Reference data is exposed as MCP Resources (see Resources section). MCP clients that support the resources protocol can access them directly.

Available References:

• resource://mapbox-style-layers - Mapbox GL JS style specification reference guide covering all layer types (fill, line, symbol, circle, fill-extrusion) and their properties
• resource://mapbox-streets-v8-fields - Complete field definitions for all Mapbox Streets v8 source layers, including enumerated values for each field (useful for building filters)
• resource://mapbox-token-scopes - Comprehensive token scope reference explaining what each scope allows and which scopes are needed for different operations
• resource://mapbox-layer-type-mapping - Mapping of Mapbox Streets v8 source layers to compatible GL JS layer types, with common usage patterns

Example prompts:

• "What fields are available for the landuse layer?"
• "Show me the token scopes reference"
• "What layer type should I use for roads?"
• "Get the Streets v8 fields reference"
• "What scopes do I need to display a map?"

Style Management Tools

Complete set of tools for managing Mapbox styles via the Styles API:

Style Builder Tool - Create and modify Mapbox styles programmatically through conversational prompts

📖 See the Style Builder documentation for detailed usage and examples →

ListStylesTool - List all styles for a Mapbox account

• Input: limit (optional - max number of styles), start (optional - pagination token)
• Returns: Array of style metadata with optional pagination info

CreateStyleTool - Create a new Mapbox style

• Input: name, style (Mapbox style specification)
• Returns: Created style details with ID

RetrieveStyleTool - Retrieve a specific style by ID

• Input: styleId
• Returns: Complete style specification

UpdateStyleTool - Update an existing style

• Input: styleId, name (optional), style (optional)
• Returns: Updated style details

DeleteStyleTool - Delete a style by ID

• Input: styleId
• Returns: Success confirmation

PreviewStyleTool - Generate preview URL for a Mapbox style using an existing public token

• Input: styleId, title (optional), zoomwheel (optional), zoom (optional), center (optional), bearing (optional), pitch (optional)
• Returns: URL to open the style preview in browser
• Note: This tool automatically fetches the first available public token from your account for the preview URL. Requires at least one public token with styles:read scope.

ValidateStyleTool - Validate Mapbox style JSON against the Mapbox Style Specification

• Input: style (Mapbox style JSON object or JSON string)
• Returns: Validation results including errors, warnings, info messages, and style summary
• Performs comprehensive offline validation checking:
  • Required fields (version, sources, layers)
  • Valid layer and source types
  • Source references and layer IDs
  • Common configuration issues
• Note: This is an offline validation tool that doesn't require API access or token scopes

⚠️ Required Token Scopes:

All style tools require a valid Mapbox access token with specific scopes. Using a token without the correct scope will result in authentication errors.

• ListStylesTool: Requires styles:list scope
• CreateStyleTool: Requires styles:write scope
• RetrieveStyleTool: Requires styles:download scope
• UpdateStyleTool: Requires styles:write scope
• DeleteStyleTool: Requires styles:write scope
• PreviewStyleTool: Requires tokens:read scope (to list tokens) and at least one public token with styles:read scope

Note: The username is automatically extracted from the JWT token payload.

Example prompts:

• "Can you create a Christmas themed Style for me?"
• "Please generate a preview link for this style"
• "Can you change the background to snow style?"

Token Management Tools

create-token

Create a new Mapbox access token with specified scopes and optional URL restrictions.

Parameters:

• note (string, required): Description of the token
• scopes (array of strings, required): Array of scopes/permissions for the token. Must be valid Mapbox scopes (see below)
• allowedUrls (array of strings, optional): URLs where the token can be used (max 100)
• expires (string, optional): Expiration time in ISO 8601 format (maximum 1 hour in the future)

Available Scopes:

Available scopes for public tokens:

• styles:tiles - Read styles as raster tiles
• styles:read - Read styles
• fonts:read - Read fonts
• datasets:read - Read datasets
• vision:read - Read Vision API

Example:

{
  "note": "Development token for my app",
  "scopes": ["styles:read", "fonts:read"],
  "allowedUrls": ["https://myapp.com"]
}

Example prompts:

• "Create a new Mapbox token for my web app with styles:read and fonts:read permissions"
• "Generate a token that expires in 30 minutes with styles:tiles and vision:read scopes"
• "Create a restricted token that only works on https://myapp.com with styles:read, fonts:read, and datasets:read"

list-tokens

List Mapbox access tokens for the authenticated user with optional filtering and pagination.

Parameters:

• default (boolean, optional): Filter to show only the default public token
• limit (number, optional): Maximum number of tokens to return per page (1-100)
• sortby (string, optional): Sort tokens by "created" or "modified" timestamp
• start (string, optional): The token ID after which to start the listing (when provided, auto-pagination is disabled)
• usage (string, optional): Filter by token type: "pk" (public)

Pagination behavior:

• When no start parameter is provided, the tool automatically fetches all pages of results
• When a start parameter is provided, only the requested page is returned (for manual pagination control)

Example:

{
  "limit": 10,
  "sortby": "created",
  "usage": "pk"
}

Example prompts:

• "List all my Mapbox tokens"
• "Show me my public tokens sorted by creation date"
• "Find my default public token"
• "List the 5 most recently modified tokens"
• "Show all public tokens in my account"

Feedback Tools

Access user feedback items from the Mapbox Feedback API. These tools allow you to retrieve and view user-reported issues, suggestions, and feedback about map data, routing, and POI details.

list_feedback_tool - List user feedback items with comprehensive filtering, sorting, and pagination options.

Parameters:

• feedback_ids (array of UUIDs, optional): Filter by one or more feedback item IDs
• after (string, optional): Cursor from a previous response for pagination
• limit (number, optional): Maximum number of items to return (1-1000, default varies)
• sort_by (string, optional): Sort field - received_at (default), created_at, or updated_at
• order (string, optional): Sort direction - asc (default) or desc
• status (array, optional): Filter by status - received, fixed, reviewed, out_of_scope
• category (array, optional): Filter by feedback categories
• search (string, optional): Search phrase to match against feedback text
• trace_id (array, optional): Filter by trace IDs
• created_before, created_after (ISO 8601 string, optional): Filter by creation date range
• received_before, received_after (ISO 8601 string, optional): Filter by received date range
• updated_before, updated_after (ISO 8601 string, optional): Filter by update date range
• format (string, optional): Output format - formatted_text (default) or json_string

Returns: Paginated list of feedback items with pagination cursors.

get_feedback_tool - Get a single user feedback item by its unique ID.

Parameters:

• feedback_id (UUID, required): The unique identifier of the feedback item
• format (string, optional): Output format - formatted_text (default) or json_string

Returns: Single feedback item with details including status, category, feedback text, location, and timestamps.

⚠️ Required Token Scope:

• Both feedback tools: Require user-feedback:read scope on the access token

Example prompts:

• "List all feedback items with status 'fixed'"
• "Show me feedback items in the 'poi_details' category created after July 1st"
• "Get feedback item with ID 40eae4c7-b157-4b49-a091-7e1099bba77e"
• "Find feedback items containing 'apartment building' in the feedback text"
• "List all routing issue feedback from the last month"

Local Processing Tools

GeoJSON Preview tool (Beta)

Generate a geojson.io URL to visualize GeoJSON data. This tool:

• Validates GeoJSON format (Point, LineString, Polygon, Feature, FeatureCollection, etc.)
• Returns a direct URL to geojson.io for instant visualization
• Supports both GeoJSON objects and JSON strings as input

Example usage:

{
  "geojson": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }
}

Returns: A single URL string that can be opened in a browser to view the GeoJSON data.

Note: This is a beta feature currently optimized for small to medium-sized GeoJSON files. Large GeoJSON files may result in very long URLs and slower performance. We plan to optimize this in future versions by implementing alternative approaches for handling large datasets.

Example prompts:

• "Generate a preview URL for this GeoJSON data"
• "Create a geojson.io link for my uploaded route.geojson file"

Validate GeoJSON tool

Validates GeoJSON objects for correctness, checking structure, coordinates, and geometry types. This offline validation tool performs comprehensive checks on GeoJSON data without requiring API access.

Parameters:

• geojson (string or object, required): GeoJSON object or JSON string to validate

What it validates:

• GeoJSON type validity (Feature, FeatureCollection, Point, LineString, Polygon, etc.)
• Required properties (type, coordinates, geometry, features)
• Coordinate array structure and position validity
• Longitude ranges [-180, 180] and latitude ranges [-90, 90]
• Polygon ring closure (first and last coordinates should match)
• Minimum position requirements (LineString needs 2+, Polygon rings need 4+ positions)

Returns:

Validation results including:

• valid (boolean): Overall validity
• errors (array): Critical errors that make the GeoJSON invalid
• warnings (array): Non-critical issues (e.g., unclosed polygon rings, out-of-range coordinates)
• info (array): Informational messages
• statistics: Object with type, feature count, geometry types, and bounding box

Each issue includes:

• severity: "error", "warning", or "info"
• message: Description of the issue
• path: JSON path to the problem (optional)
• suggestion: How to fix the issue (optional)

Example:

{
  "geojson": {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [102.0, 0.5]
    },
    "properties": {
      "name": "Test Point"
    }
  }
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [],
  "statistics": {
    "type": "Feature",
    "featureCount": 1,
    "geometryTypes": ["Point"],
    "bbox": [102.0, 0.5, 102.0, 0.5]
  }
}

Example prompts:

• "Validate this GeoJSON file and tell me if there are any errors"
• "Check if my GeoJSON coordinates are valid"
• "Is this Feature Collection properly formatted?"

Note: This is an offline validation tool that doesn't require API access or token scopes.

Validate Expression tool

Validates Mapbox style expressions for syntax, operators, and argument correctness. This offline validation tool performs comprehensive checks on Mapbox expressions without requiring API access.

Parameters:

• expression (array or string, required): Mapbox expression to validate (array format or JSON string)

What it validates:

• Expression syntax and structure
• Valid operator names
• Correct argument counts for each operator
• Nested expression validation
• Expression depth (warns about deeply nested expressions)

Returns:

Validation results including:

• valid (boolean): Overall validity
• errors (array): Critical errors that make the expression invalid
• warnings (array): Non-critical issues (e.g., deeply nested expressions)
• info (array): Informational messages
• metadata: Object with expressionType, returnType, and depth

Each issue includes:

• severity: "error", "warning", or "info"
• message: Description of the issue
• path: Path to the problem in the expression (optional)
• suggestion: How to fix the issue (optional)

Supported expression types:

• Data: get, has, id, geometry-type, feature-state, properties
• Lookup: at, in, index-of, slice, length
• Decision: case, match, coalesce
• Ramps & interpolation: interpolate, step
• Math: +, -, *, /, %, ^, sqrt, log10, log2, ln, abs, etc.
• String: concat, downcase, upcase, is-supported-script
• Color: rgb, rgba, to-rgba, hsl, hsla
• Type: array, boolean, collator, format, image, literal, number, number-format, object, string, to-boolean, to-color, to-number, to-string, typeof
• Camera: zoom, pitch, distance-from-center
• Variable binding: let, var

Example:

{
  "expression": ["get", "population"]
}

Returns:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [
    {
      "severity": "info",
      "message": "Expression validated successfully"
    }
  ],
  "metadata": {
    "expressionType": "data",
    "returnType": "any",
    "depth": 1
  }
}

Example prompts:

• "Validate this Mapbox expression: ["get", "population"]"
• "Check if this interpolation expression is correct"
• "Is this expression syntax valid for Mapbox styles?"

Note: This is an offline validation tool that doesn't require API access or token scopes.

Coordinate Conversion tool

Convert coordinates between different coordinate reference systems (CRS), specifically between WGS84 (EPSG:4326) and Web Mercator (EPSG:3857).

Parameters:

• coordinates (array, required): Array of coordinate pairs to convert. Each coordinate pair should be [longitude, latitude] for WGS84 or [x, y] for Web Mercator
• fromCRS (string, required): Source coordinate reference system. Supported values: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)
• toCRS (string, required): Target coordinate reference system. Supported values: "EPSG:4326" (WGS84), "EPSG:3857" (Web Mercator)

Returns:

An array of converted coordinate pairs in the target CRS format.

Example:

{
  "coordinates": [
    [-122.4194, 37.7749],
    [-74.006, 40.7128]
  ],
  "fromCRS": "EPSG:4326",
  "toCRS": "EPSG:3857"
}

Example prompts:

• "Convert these coordinates from WGS84 to Web Mercator: [-122.4194, 37.7749] and [-74.006, 40.7128]"
• "Convert the coordinates [-13627361.0, 4544761.0] from Web Mercator to WGS84"

Bounding Box tool

Calculates the bounding box of given GeoJSON content, returning coordinates as [minX, minY, maxX, maxY].

Parameters:

• geojson (string or object, required): GeoJSON content to calculate bounding box for. Can be provided as:
  • A JSON string that will be parsed
  • A GeoJSON object

Supported GeoJSON types:

• Point
• LineString
• Polygon
• MultiPoint
• MultiLineString
• MultiPolygon
• GeometryCollection
• Feature
• FeatureCollection

Returns:

An array of four numbers representing the bounding box: [minX, minY, maxX, maxY]

• minX: Western-most longitude
• minY: Southern-most latitude
• maxX: Eastern-most longitude
• maxY: Northern-most latitude

Example:

{
  "geojson": {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-73.9857, 40.7484]
        },
        "properties": {}
      },
      {
        "type": "Feature",
        "geometry": {
          "type": "Point",
          "coordinates": [-74.006, 40.7128]
        },
        "properties": {}
      }
    ]
  }
}

Example prompts:

• "Calculate the bounding box of this GeoJSON file" (then upload a .geojson file)
• "What's the bounding box for the coordinates in the uploaded parks.geojson file?"

Color Contrast Checker tool

Checks color contrast ratios between foreground and background colors for WCAG 2.1 accessibility compliance.

Parameters:

• foregroundColor (string, required): Foreground color (text color) in any CSS format (hex, rgb, rgba, named colors)
• backgroundColor (string, required): Background color in any CSS format (hex, rgb, rgba, named colors)
• level (string, optional): WCAG conformance level to check against ("AA" or "AAA", default: "AA")
• fontSize (string, optional): Font size category ("normal" or "large", default: "normal")
  • Normal: < 18pt or < 14pt bold
  • Large: ≥ 18pt or ≥ 14pt bold

Color format support:

• Hex colors: #RGB, #RRGGBB, #RRGGBBAA
• RGB/RGBA: rgb(r, g, b), rgba(r, g, b, a)
• Named colors: black, white, red, blue, gray, etc.

WCAG 2.1 requirements:

• WCAG AA: 4.5:1 for normal text, 3:1 for large text
• WCAG AAA: 7:1 for normal text, 4.5:1 for large text

Returns:

A JSON object with:

• contrastRatio: Calculated contrast ratio (e.g., 21 for black on white)
• passes: Whether the combination meets the specified WCAG level
• level: WCAG level checked ("AA" or "AAA")
• fontSize: Font size category ("normal" or "large")
• minimumRequired: Minimum contrast ratio required for the level and font size
• wcagRequirements: Complete WCAG contrast requirements for all levels
• recommendations: Array of suggestions (only included when contrast fails)

Example:

{
  "contrastRatio": 21,
  "passes": true,
  "level": "AA",
  "fontSize": "normal",
  "minimumRequired": 4.5,
  "wcagRequirements": {
    "AA": { "normal": 4.5, "large": 3.0 },
    "AAA": { "normal": 7.0, "large": 4.5 }
  }
}

Example prompts:

• "Check if black text on white background is WCAG AA compliant"
• "What's the contrast ratio between #4264fb and white?"
• "Does gray text (#767676) on white meet AAA standards for large text?"
• "Check color contrast for rgb(51, 51, 51) on rgb(245, 245, 245)"
• "Is this color combination accessible: foreground 'navy' on background 'lightblue'?"

compare_styles_tool

Compares two Mapbox styles and reports structural differences, including changes to layers, sources, and properties. This offline comparison tool performs deep object comparison without requiring API access.

Parameters: