mcp-devkit-server

# 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](https://github.com/mapbox/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](#mapbox-developer-mcp-server)
  - [Table of Contents](#table-of-contents)
  - [Quick Start](#quick-start)
    - [Integration with Developer Tools](#integration-with-developer-tools)
    - [DXT Package Distribution](#dxt-package-distribution)
      - [Creating the DXT Package](#creating-the-dxt-package)
    - [Hosted MCP Endpoint](#hosted-mcp-endpoint)
    - [Getting Your Mapbox Access Token](#getting-your-mapbox-access-token)
  - [Tools](#tools)
    - [Reference Tools](#reference-tools)
    - [Style Management Tools](#style-management-tools)
    - [Token Management Tools](#token-management-tools)
      - [create-token](#create-token)
      - [list-tokens](#list-tokens)
    - [Feedback Tools](#feedback-tools)
    - [Local Processing Tools](#local-processing-tools)
      - [GeoJSON Preview tool (Beta)](#geojson-preview-tool-beta)
      - [Coordinate Conversion tool](#coordinate-conversion-tool)
      - [Bounding Box tool](#bounding-box-tool)
      - [compare_styles_tool](#compare_styles_tool)
      - [Style Optimization tool](#style-optimization-tool)
  - [Resources](#resources)
  - [Observability \& Tracing](#observability--tracing)
    - [Features](#features)
    - [Quick Start with Jaeger](#quick-start-with-jaeger)
    - [Supported Backends](#supported-backends)
    - [Documentation](#documentation)
    - [Environment Variables](#environment-variables)
  - [Development](#development)
    - [Testing](#testing)
      - [Tool Snapshot Tests](#tool-snapshot-tests)
    - [Inspecting Server](#inspecting-server)
      - [Using Node.js](#using-nodejs)
      - [Using Docker](#using-docker)
    - [Creating New Tools](#creating-new-tools)
    - [Environment Variables](#environment-variables-1)
      - [VERBOSE_ERRORS](#verbose_errors)
  - [Troubleshooting](#troubleshooting)
  - [Release Process](#release-process)
  - [Contributing](#contributing)

## Quick Start

### Integration with Developer Tools

Get started by integrating with your preferred AI development environment:

- [Claude Code Integration](./docs/claude-code-integration.md) - Command-line development with Claude
- [Claude Desktop Integration](./docs/claude-desktop-integration.md) - Desktop application integration
- [Cursor Integration](./docs/cursor-integration.md) - Cursor IDE integration
- [VS Code Integration](./docs/vscode-integration.md) - 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:

```bash
# 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](https://github.com/mapbox/mcp-server/blob/main/docs/hosted-mcp-guide.md). 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](https://www.mapbox.com/signup/)
2. Navigate to your [Account page](https://account.mapbox.com/)
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](https://docs.mapbox.com/help/dive-deeper/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](#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 →](./docs/STYLE_BUILDER.md)**

**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:**

```json
{
  "note": "Development token for my app",
  "scopes": ["styles:read", "fonts:read"],
  "allowedUrls": ["