Mapbox Mcp

Mapbox MCP

AI-Powered 2D/3D Map Control via Model Context Protocol

Connect any MCP-compatible AI agent to Mapbox GL JS — camera, layers, markers, sources, 3D terrain, all through natural language.

中文文档

---

Architecture

+----------------+   stdio    +--------------------+  WebSocket  +--------------------+
|   AI Agent     |  |  mapbox-mcp-       |  |  mapbox-mcp-       |
|   (Claude,     |    MCP     |  runtime           |   JSON-RPC  |  bridge            |
|    Cursor...)  |            |  (Node.js)         |    2.0      |  (Browser)         |
+----------------+            +--------------------+             +--------------------+
                                                                         |
                                                                  +------v------+
                                                                  |  Mapbox GL  |
                                                                  |  JS Map     |
                                                                  +-------------+

Packages

| Package | Description | |---------|-------------| | [mapbox-mcp-runtime](packages/mapbox-mcp-runtime/) | MCP Server (stdio) -- 40+ tools across 8 toolsets, WebSocket bridge to browser | | [mapbox-mcp-bridge](packages/mapbox-mcp-bridge/) | Browser SDK -- receives commands via WebSocket and controls Mapbox GL JS |

Quick Start

1. Install & Build

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

2. Start the MCP Runtime

npx mapbox-mcp-runtime
# => HTTP + WebSocket server on http://localhost:9200
# => MCP Server running (stdio), 30 tools registered

3. Connect Browser

Open examples/minimal/index.html in a browser, enter your Mapbox access token. The bridge auto-connects to ws://localhost:9200.

Or integrate the bridge in your own app:

import { MapboxBridge } from 'mapbox-mcp-bridge'

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/dark-v11',
  accessToken: 'YOUR_TOKEN'
})
const bridge = new MapboxBridge(map)
bridge.connect('ws://localhost:9200')

4. Connect AI Agent

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "mapbox": {
      "command": "npx",
      "args": ["-y", "mapbox-mcp-runtime"]
    }
  }
}

Now ask your AI: "Fly to the Eiffel Tower and add a GeoJSON polygon around it"

40+ Available Tools

Tools are organized into 8 toolsets. Default mode enables 5 core toolsets (~30 tools). Use list_toolsets and enable_toolset to dynamically activate more.

| Toolset | Tools | Default | |---------|-------|---------| | view | flyTo, easeTo, jumpTo, getView, fitBounds, resetNorth, zoomIn, zoomOut | Yes | | layer | addLayer, removeLayer, listLayers, setLayerVisibility, setPaintProperty, setLayoutProperty, setFilter, moveLayer | Yes | | source | addSource, removeSource, listSources, getSourceData, setSourceData | Yes | | marker | addMarker, removeMarker, updateMarker, listMarkers | Yes | | interaction | screenshot, queryRenderedFeatures, querySourceFeatures | Yes | | draw | addGeoJSON, addImage, removeImage | No | | style | setStyle, getStyle, setFog, setLight, setTerrain, setSky | No | | 3d | addFillExtrusion, add3DModel | No | | geolocation | geocode | No |

Meta Tools (always available)

| Tool | Description | |------|-------------| | list_toolsets | List all available toolsets and their enabled status | | enable_toolset | Enable a toolset to register its tools |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MAPBOX_MCP_PORT | 9200 | WebSocket server port | | MAPBOX_TOOLSETS | view,layer,source,marker,interaction | Comma-separated default toolsets |

Development

# Dev mode (auto-restart)
cd packages/mapbox-mcp-runtime
npm run dev

# Build all packages
npm run build

Inspired By

This project follows the architecture of cesium-mcp, adapted for the Mapbox GL JS ecosystem.

Related Projects

• cesium-mcp — AI control for CesiumJS 3D globe
• openlayers-mcp — AI control for OpenLayers

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gaopengbin
• Source: gaopengbin/mapbox-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.