@mapbox/mcp-devkit-server
Advanced tools
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.
https://github.com/user-attachments/assets/8b1b8ef2-9fba-4951-bc9a-beaed4f6aff6
Get started by integrating with your preferred AI development environment:
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.
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:
dist/esm/index.js)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.
A Mapbox access token is required to use this MCP server.
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:
styles:read scopestyles:write scopetokens:read and tokens:write scopesuser-feedback:read scopeget_latest_mapbox_docs_tool - Access the latest official Mapbox documentation directly from the source. This tool fetches comprehensive, up-to-date information about all Mapbox APIs, SDKs, and developer resources from docs.mapbox.com/llms.txt.
Example prompts:
š See more examples and interactive demo ā
get_reference_tool - Access static Mapbox reference documentation and schemas. This tool provides essential reference information that helps AI assistants understand Mapbox concepts and build correct styles and tokens.
Note: This tool exists as a workaround for Claude Desktop's current limitation with MCP resources. Claude Desktop can see resources (via
resources/list) but doesn't automatically callresources/readto fetch their content. This tool provides the same reference data through the tool interface, which Claude Desktop does support. Other MCP clients that fully support the resources protocol can access this data directly as MCP Resources (see Resources section below).
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 propertiesresource://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 operationsresource://mapbox-layer-type-mapping - Mapping of Mapbox Streets v8 source layers to compatible GL JS layer types, with common usage patternsExample prompts:
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
limit (optional - max number of styles), start (optional - pagination token)CreateStyleTool - Create a new Mapbox style
name, style (Mapbox style specification)RetrieveStyleTool - Retrieve a specific style by ID
styleIdUpdateStyleTool - Update an existing style
styleId, name (optional), style (optional)DeleteStyleTool - Delete a style by ID
styleIdPreviewStyleTool - Generate preview URL for a Mapbox style using an existing public token
styleId, title (optional), zoomwheel (optional), zoom (optional), center (optional), bearing (optional), pitch (optional)styles:read scope.ValidateStyleTool - Validate Mapbox style JSON against the Mapbox Style Specification
style (Mapbox style JSON object or JSON string)ā ļø 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.
styles:list scopestyles:write scopestyles:download scopestyles:write scopestyles:write scopetokens:read scope (to list tokens) and at least one public token with styles:read scopeNote: The username is automatically extracted from the JWT token payload.
Example prompts:
Create a new Mapbox access token with specified scopes and optional URL restrictions.
Parameters:
note (string, required): Description of the tokenscopes (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 tilesstyles:read - Read stylesfonts:read - Read fontsdatasets:read - Read datasetsvision:read - Read Vision APIExample:
{
"note": "Development token for my app",
"scopes": ["styles:read", "fonts:read"],
"allowedUrls": ["https://myapp.com"]
}
Example prompts:
List Mapbox access tokens for the authenticated user with optional filtering and pagination.
Parameters:
default (boolean, optional): Filter to show only the default public tokenlimit (number, optional): Maximum number of tokens to return per page (1-100)sortby (string, optional): Sort tokens by "created" or "modified" timestampstart (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:
start parameter is provided, the tool automatically fetches all pages of resultsstart parameter is provided, only the requested page is returned (for manual pagination control)Example:
{
"limit": 10,
"sortby": "created",
"usage": "pk"
}
Example prompts:
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 IDsafter (string, optional): Cursor from a previous response for paginationlimit (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_atorder (string, optional): Sort direction - asc (default) or descstatus (array, optional): Filter by status - received, fixed, reviewed, out_of_scopecategory (array, optional): Filter by feedback categoriessearch (string, optional): Search phrase to match against feedback texttrace_id (array, optional): Filter by trace IDscreated_before, created_after (ISO 8601 string, optional): Filter by creation date rangereceived_before, received_after (ISO 8601 string, optional): Filter by received date rangeupdated_before, updated_after (ISO 8601 string, optional): Filter by update date rangeformat (string, optional): Output format - formatted_text (default) or json_stringReturns: 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 itemformat (string, optional): Output format - formatted_text (default) or json_stringReturns: Single feedback item with details including status, category, feedback text, location, and timestamps.
ā ļø Required Token Scope:
user-feedback:read scope on the access tokenExample prompts:
Generate a geojson.io URL to visualize GeoJSON data. This tool:
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:
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 validateWhat it validates:
Returns:
Validation results including:
valid (boolean): Overall validityerrors (array): Critical errors that make the GeoJSON invalidwarnings (array): Non-critical issues (e.g., unclosed polygon rings, out-of-range coordinates)info (array): Informational messagesstatistics: Object with type, feature count, geometry types, and bounding boxEach issue includes:
severity: "error", "warning", or "info"message: Description of the issuepath: 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:
Note: This is an offline validation tool that doesn't require API access or token scopes.
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:
Returns:
Validation results including:
valid (boolean): Overall validityerrors (array): Critical errors that make the expression invalidwarnings (array): Non-critical issues (e.g., deeply nested expressions)info (array): Informational messagesmetadata: Object with expressionType, returnType, and depthEach issue includes:
severity: "error", "warning", or "info"message: Description of the issuepath: Path to the problem in the expression (optional)suggestion: How to fix the issue (optional)Supported expression types:
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:
Note: This is an offline validation tool that doesn't require API access or token scopes.
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 MercatorfromCRS (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:
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:
Supported GeoJSON types:
Returns:
An array of four numbers representing the bounding box: [minX, minY, maxX, maxY]
minX: Western-most longitudeminY: Southern-most latitudemaxX: Eastern-most longitudemaxY: Northern-most latitudeExample:
{
"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:
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")
Color format support:
#RGB, #RRGGBB, #RRGGBBAArgb(r, g, b), rgba(r, g, b, a)black, white, red, blue, gray, etc.WCAG 2.1 requirements:
Returns:
A JSON object with:
contrastRatio: Calculated contrast ratio (e.g., 21 for black on white)passes: Whether the combination meets the specified WCAG levellevel: WCAG level checked ("AA" or "AAA")fontSize: Font size category ("normal" or "large")minimumRequired: Minimum contrast ratio required for the level and font sizewcagRequirements: Complete WCAG contrast requirements for all levelsrecommendations: 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:
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:
styleA (string or object, required): First Mapbox style to compare (JSON string or style object)styleB (string or object, required): Second Mapbox style to compare (JSON string or style object)ignoreMetadata (boolean, optional): If true, ignores metadata fields (id, owner, created, modified, draft, visibility) when comparingComparison features:
Returns:
{
"identical": false,
"differences": [
{
"path": "layers.water.paint.fill-color",
"type": "modified",
"valueA": "#a0c8f0",
"valueB": "#b0d0ff",
"description": "Modified property at layers.water.paint.fill-color"
}
],
"summary": {
"totalDifferences": 1,
"added": 0,
"removed": 0,
"modified": 1
}
}
Example prompts:
Optimizes Mapbox styles by removing redundancies, simplifying expressions, and reducing file size.
Parameters:
style (string or object, required): Mapbox style to optimize (JSON string or style object)optimizations (array, optional): Specific optimizations to apply. If not specified, all optimizations are applied. Available optimizations:
remove-unused-sources: Remove sources not referenced by any layerremove-duplicate-layers: Remove layers that are exact duplicatessimplify-expressions: Simplify boolean expressions (e.g., ["all", true] ā true)remove-empty-layers: Remove layers with no visible properties (excluding background layers)consolidate-filters: Identify layers with identical filters that could be consolidatedOptimizations performed:
["all", true] ā true["any", false] ā false["!", false] ā true["!", true] ā falseReturns:
A JSON object with:
optimizedStyle: The optimized Mapbox styleoptimizations: Array of optimizations appliedsummary: Statistics including size savings and percent reductionExample:
{
"optimizedStyle": { "version": 8, "sources": {}, "layers": [] },
"optimizations": [
{
"type": "remove-unused-sources",
"description": "Removed 2 unused source(s): unused-source1, unused-source2",
"count": 2
}
],
"summary": {
"totalOptimizations": 2,
"originalSize": 1234,
"optimizedSize": 890,
"sizeSaved": 344,
"percentReduction": 27.88
}
}
Example prompts:
This repository includes Agent Skills that provide domain expertise for building maps with Mapbox. Skills teach AI assistants about map design, security best practices, and common implementation patterns.
Available Skills:
Skills complement the MCP server by providing expertise (how to think about design) while tools provide capabilities (how to execute actions).
For complete documentation and usage instructions, see skills/README.md.
To use these skills in Claude Code, create a symlink:
mkdir -p .claude
ln -s ../skills .claude/skills
Or copy to your global skills directory:
cp -r skills/* ~/.claude/skills/
Upload skills as zip files via the Skills API. See Claude API Skills documentation.
MCP Prompts are pre-built workflow templates that guide AI assistants through multi-step tasks. They orchestrate multiple tools in the correct sequence, providing best practices and error handling built-in.
Available Prompts:
Create a new Mapbox map style and generate a shareable preview link with automatic token management.
Arguments:
style_name (required): Name for the new map stylestyle_description (optional): Description of the style theme or purposebase_style (optional): Base style to start from (e.g., "streets-v12", "dark-v11")preview_location (optional): Location to center the preview mappreview_zoom (optional): Zoom level for the preview (0-22, default: 12)What it does:
styles:read scopeExample usage:
Use prompt: create-and-preview-style
Arguments:
style_name: "My Custom Map"
style_description: "A dark-themed map for nighttime navigation"
base_style: "dark-v11"
preview_location: "San Francisco"
preview_zoom: "13"
Use conversational AI to build a custom styled map based on a theme description.
Arguments:
theme (required): Theme description (e.g., "dark cyberpunk", "nature-focused", "minimal monochrome")emphasis (optional): Features to emphasize (e.g., "parks and green spaces", "transit lines")preview_location (optional): Location to center the preview mappreview_zoom (optional): Zoom level for the preview (0-22, default: 12)What it does:
Example usage:
Use prompt: build-custom-map
Arguments:
theme: "retro 80s neon"
emphasis: "nightlife and entertainment venues"
preview_location: "Tokyo"
preview_zoom: "14"
Analyze and visualize GeoJSON data with automatic validation and bounding box calculation.
Arguments:
geojson_data (required): GeoJSON object or string to analyzeshow_bounds (optional): Calculate and display bounding box (true/false, default: true)convert_coordinates (optional): Provide Web Mercator conversion examples (true/false, default: false)What it does:
Example usage:
Use prompt: analyze-geojson
Arguments:
geojson_data: {"type":"FeatureCollection","features":[...]}
show_bounds: "true"
convert_coordinates: "false"
Complete setup workflow for a new Mapbox project with proper token security and style initialization.
Arguments:
project_name (required): Name of the project or applicationproject_type (optional): Type of project: "web", "mobile", "backend", or "fullstack" (default: "web")production_domain (optional): Production domain for URL restrictions (e.g., "myapp.com")style_theme (optional): Initial style theme: "light", "dark", "streets", "outdoors", "satellite" (default: "light")What it does:
Example usage:
Use prompt: setup-mapbox-project
Arguments:
project_name: "Restaurant Finder"
project_type: "fullstack"
production_domain: "restaurantfinder.com"
style_theme: "light"
Systematic troubleshooting workflow for diagnosing and fixing Mapbox integration issues.
Arguments:
issue_description (required): Description of the problem (e.g., "map not loading", "401 error")error_message (optional): Exact error message from console or logsstyle_id (optional): Mapbox style ID being used, if applicableenvironment (optional): Where the issue occurs: "development", "production", "staging"What it does:
Example usage:
Use prompt: debug-mapbox-integration
Arguments:
issue_description: "Getting 401 errors when map loads"
error_message: "401 Unauthorized"
style_id: "my-style-id"
environment: "production"
Create a map style with data-driven properties that respond dynamically to feature data using expressions.
Arguments:
style_name (required): Name for the data-driven styledata_description (required): Description of the data (e.g., "population by city", "earthquake magnitudes")property_name (required): Name of the data property to visualize (e.g., "population", "magnitude")visualization_type (optional): How to visualize: "color", "size", "both", "heatmap" (default: "color")color_scheme (optional): Color scheme: "sequential", "diverging", "categorical" (default: "sequential")What it does:
Example usage:
Use prompt: design-data-driven-style
Arguments:
style_name: "Population Density Map"
data_description: "City population data"
property_name: "population"
visualization_type: "both"
color_scheme: "sequential"
Comprehensive quality validation workflow for Mapbox styles before production deployment.
Arguments:
style_id_or_json (required): Either a Mapbox style ID or complete style JSONskip_optimization (optional): Set to "true" to skip style optimization (default: false)wcag_level (optional): WCAG compliance level: "AA" or "AAA" (default: "AA")What it does:
Example usage:
Use prompt: prepare-style-for-production
Arguments:
style_id_or_json: "username/my-style-id"
wcag_level: "AA"
skip_optimization: "false"
Related:
See the mapbox-style-quality skill for detailed guidance on when to use validation tools, best practices, and optimization strategies.
This server exposes static reference documentation as MCP Resources. While these are primarily accessed through the get_reference_tool, MCP clients that fully support the resources protocol can access them directly.
Available Resources:
Mapbox Style Specification Guide (resource://mapbox-style-layers)
Mapbox Streets v8 Fields Reference (resource://mapbox-streets-v8-fields)
landuse layer has class field with values like park, cemetery, hospital, etc.Mapbox Token Scopes Reference (resource://mapbox-token-scopes)
Mapbox Layer Type Mapping (resource://mapbox-layer-type-mapping)
Accessing Resources:
get_reference_tool to access these referencesNote: Resources provide static reference data that doesn't change frequently, while tools provide dynamic, user-specific data (like listing your styles or tokens) and perform actions (like creating styles or tokens).
This server includes comprehensive distributed tracing using OpenTelemetry (OTEL) for production-ready observability.
# 1. Start Jaeger (Docker required)
npm run tracing:jaeger:start
# 2. Configure environment
cp .env.example .env
# Edit .env to add MAPBOX_ACCESS_TOKEN
# OTEL_EXPORTER_OTLP_ENDPOINT is already set to http://localhost:4318
# 3. Run the server
npm run inspect:build
# 4. View traces at http://localhost:16686
# 5. Stop Jaeger when done
npm run tracing:jaeger:stop
The server supports any OTLP-compatible backend including:
See .env.example for configuration examples for each platform.
# Enable tracing (required)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# Optional configuration
OTEL_SERVICE_NAME=mapbox-mcp-devkit-server
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1 # Sample 10% for high-volume
The project includes snapshot tests to ensure tool integrity and prevent accidental additions or removals of tools. These tests automatically discover all tools and create a snapshot of their metadata.
What the snapshot test covers:
PascalCaseTool convention, e.g., ListStylesTool)snake_case_tool convention, e.g., list_styles_tool)When to update snapshots:
Adding a new tool: After creating a new tool, run the test with snapshot update flag:
npm test -- test/tools/tool-naming-convention.test.ts --updateSnapshot
Removing a tool: After removing a tool, update the snapshot:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot
Modifying tool metadata: If you change a tool's name or description, update the snapshot:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot
Running snapshot tests:
# Run all tests (snapshot will fail if tools have changed)
npm test
# Update snapshots after intentional changes
npm test -- --updateSnapshot
Important: Only update snapshots when you have intentionally added, removed, or modified tools. Unexpected snapshot failures indicate accidental changes to the tool structure.
# Run the built image
npm run inspect:build
# Build the Docker image
docker build -t mapbox-mcp-devkit .
# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-devkit
npx plop create-tool
# 1. Choose tool type:
# - Mapbox tool (makes API calls to Mapbox services)
# - Local tool (local processing, no API calls)
# 2. Provide tool name without suffix using PascalCase (e.g. Search)
Generated file structure:
The plop generator creates three files for each new tool:
src/tools/your-tool-name-tool/
āāā YourToolNameTool.schema.ts # Input schema definition and types
āāā YourToolNameTool.ts # Main tool implementation
āāā YourToolNameTool.test.ts # Unit tests
After creating a new tool:
Update the input schema in YourToolNameTool.schema.ts:
Update the tool description in YourToolNameTool.ts:
Implement the tool logic in the execute method
Update test cases with actual test data in YourToolNameTool.test.ts
Update the snapshot test to include the new tool:
npm test -- src/tools/tool-naming-convention.test.ts --updateSnapshot
Run all tests to ensure everything works:
npm test
Schema separation benefits:
Set VERBOSE_ERRORS=true to get detailed error messages from the MCP server. This is useful for debugging issues when integrating with MCP clients.
By default, the server returns generic error messages. With verbose errors enabled, you'll receive the actual error details, which can help diagnose API connection issues, invalid parameters, or other problems.
Interactive Previews: MCP Apps (primary) & MCP-UI (compatibility)
This server actively invests in MCP Apps as its primary interactive preview protocol, delivering self-contained HTML app panels directly inside the chat. MCP Apps is supported by Claude Desktop, VS Code with GitHub Copilot, and Claude Code ā no configuration needed.
MCP-UI (@mcp-ui/server) is also maintained for backwards compatibility with clients like Goose. It is not being removed, but new interactive preview development is focused on MCP Apps.
Supported Tools:
preview_style_tool - Interactive Mapbox style preview panelgeojson_preview_tool - Interactive GeoJSON visualization panelstyle_comparison_tool - Side-by-side style comparison panelClient support:
| Client | MCP Apps | MCP-UI |
|---|---|---|
| Claude Desktop | ā | |
| VS Code with GitHub Copilot | ā | |
| Claude Code | ā | |
| Goose | ā | ā |
| Other clients |
Disabling MCP-UI (Optional):
MCP Apps support is always active. If you want to disable the MCP-UI UIResource (used by Goose):
Via environment variable:
export ENABLE_MCP_UI=false
Or via command-line flag:
node dist/esm/index.js --disable-mcp-ui
Note: You typically don't need to disable this. All clients receive a usable text URL regardless; interactive previews are a progressive enhancement on top.
Resource Fallback Tools (Opt-In for Non-Compliant Clients)
Resources are a core MCP feature supported by most clients (Claude Desktop, VS Code, MCP Inspector, etc.). However, some clients (like smolagents) don't support resources at all. For these clients, the server can provide "resource fallback tools" that deliver the same content as resources but via tool calls.
Fallback Tools:
get_reference_tool - Access to style layers, Streets v8 fields, token scopes, layer type mappingget_latest_mapbox_docs_tool - Access to Mapbox documentationBy default, these tools are NOT included (assumes your client supports resources). If your client doesn't support resources, enable the fallback tools:
export CLIENT_NEEDS_RESOURCE_FALLBACK=true
When to set this:
true if using smolagents or other clients without resource supportIssue: Tools fail with authentication errors
Solution: Check that your MAPBOX_ACCESS_TOKEN has the required scopes for the tool you're using. See the token scopes section above.
Issue: Large GeoJSON files cause slow performance
Solution: The GeoJSON preview tool may be slow with very large files. Consider simplifying geometries or using smaller datasets for preview purposes.
Follow these steps to publish a new release:
Bump the version in package.json to the target version (e.g., 1.0.0).
Sync versions across manifest.json and server.json:
node scripts/sync-manifest-version.cjs
This reads the version from package.json and updates manifest.json and server.json (including packages[0].version) to match.
Prepare the changelog ā this replaces the "Unreleased" heading with the version and date:
npm run changelog:prepare-release 1.0.0
Commit, tag, and push:
git add package.json manifest.json server.json CHANGELOG.md
git commit -m "Release v1.0.0"
git tag v1.0.0
git push && git push --tags
Publish via the mcp-server-publisher workflow:
mcp-server-publisher repomcp-devkit-server from the repository dropdownpackage.json version@mapbox/mcp-devkit-server), publish to the MCP Registry, create a DXT package, and create a GitHub ReleaseThe following files must have matching versions before publishing:
| File | Fields |
|---|---|
package.json | version (source of truth) |
manifest.json | version |
server.json | version, packages[0].version |
The sync-manifest-version.cjs script handles syncing these automatically from package.json.
To publish a pre-release from a feature branch:
package.json with a pre-release suffix (e.g., 1.0.0-dev or 1.0.0-beta)node scripts/sync-manifest-version.cjsdev tag (won't affect latest)We welcome contributions to the Mapbox Development MCP Server! Please review our documentation:
FAQs
Mapbox MCP devkit server
The npm package @mapbox/mcp-devkit-server receives a total of 245 weekly downloads. As such, @mapbox/mcp-devkit-server popularity was classified as not popular.
We found that @mapbox/mcp-devkit-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.Ā It has 28 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
We identified over 20 additional malicious extensions, along with over 20 related sleeper extensions, some of which have already been weaponized.
Security News
TC39ās March 2026 meeting advanced eight ECMAScript proposals, including Temporal reaching Stage 4 and securing its place in the ECMAScript 2026 specification.
Research
/Security News
Since January 31, 2026, we identified at least 72 additional malicious Open VSX extensions, including transitive GlassWorm loader extensions targeting developers.