/mapbox-mcp-devkit-patterns

Mapbox MCP DevKit Patterns

Quick reference for using Mapbox MCP DevKit Server in AI coding workflows.

What is DevKit?

MCP server that gives AI assistants access to Mapbox developer APIs for style management, token creation, validation, and documentation.

Repo: https://github.com/mapbox/mcp-devkit-server

Setup

Hosted (Recommended)

Use Mapbox's hosted server - no installation needed.

Claude Desktop:

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "mapbox-devkit-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp-devkit.mapbox.com/mcp"]
    }
  }
}

Claude Code:

User-level (all projects) in ~/.claude.json:

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

Or project-level (specific project) in .mcp.json:

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

Cursor:

// .cursor/mcp.json or ~/.cursor/mcp.json
{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

VS Code with Copilot:

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

Self-Hosted (Advanced)

git clone https://github.com/mapbox/mcp-devkit-server.git
cd mcp-devkit-server && npm install && npm run build

Configure in Claude Desktop config:

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

Core Tools

Style Management

Token Management

Validation & Analysis

Geographic Utilities

Feedback & Data

Documentation

Common Workflows

Create Style

"Create a style for a real estate app:
- Emphasize property boundaries in purple
- Show parks in green
- Muted roads
- 3D buildings at zoom 15+"

Returns: Style ID and preview URL

Create Scoped Token

"Create a token with:
- styles:read, fonts:read
- Restricted to: localhost, example.com"

Validate Data

"Validate this GeoJSON:
{ \"type\": \"FeatureCollection\", ... }

Check for:
- Valid coordinates
- Required properties: name, address"

Iterative Development

1. "Create a light style for a delivery app"
2. [View preview URL]
3. "Add restaurant POIs with icons"
4. "Make delivery zones semi-transparent"
5. [Iterate until satisfied]

When to Use DevKit

Validation Patterns

// Validate before using
"Validate GeoJSON" → Fix issues → Create style

// Validate expressions
"Is ['case', ['<', ['get', 'pop'], 1000], 'small', 'large'] valid?"

// Convert coordinates
"Convert -122.4194, 37.7749 to Web Mercator"

Token Scopes

Best practice: Use minimal scopes + URL restrictions

Example: Multi-Environment Setup

"Create 3 environments:

Dev:
- Token: all scopes, localhost only
- Style: app-dev (debug labels enabled)

Staging:
- Token: read-only, staging.example.com
- Style: app-staging (production-like)

Prod:
- Token: minimal scopes, example.com
- Style: app-prod (optimized)"

Troubleshooting

Integration Patterns

With Mapbox Studio:

• DevKit: Quick creation, AI iteration
• Studio: Fine-tuning, visual editing

With Version Control:

1. "Create style and save JSON to styles/map.json"
2. Review changes in git
3. Commit to repository

With CI/CD:

1. Style JSON in repo
2. Validate via DevKit in CI
3. Deploy to Mapbox on merge

Resources

• DevKit Server
• MCP Protocol
• Style Spec
• Token Scopes