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.
+----------------+ 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 |
+-------------+
| Package | Description |
|---|---|
| mapbox-mcp-runtime | MCP Server (stdio) -- 40+ tools across 8 toolsets, WebSocket bridge to browser |
| mapbox-mcp-bridge | Browser SDK -- receives commands via WebSocket and controls Mapbox GL JS |
git clone https://github.com/gaopengbin/mapbox-mcp.git
cd mapbox-mcp
npm install
npm run buildnpx mapbox-mcp-runtime
# => HTTP + WebSocket server on http://localhost:9200
# => MCP Server running (stdio), 30 tools registeredOpen 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')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"
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 |
| Tool | Description |
|---|---|
list_toolsets |
List all available toolsets and their enabled status |
enable_toolset |
Enable a toolset to register its tools |
| Variable | Default | Description |
|---|---|---|
MAPBOX_MCP_PORT |
9200 |
WebSocket server port |
MAPBOX_TOOLSETS |
view,layer,source,marker,interaction |
Comma-separated default toolsets |
# Dev mode (auto-restart)
cd packages/mapbox-mcp-runtime
npm run dev
# Build all packages
npm run buildThis project follows the architecture of cesium-mcp, adapted for the Mapbox GL JS ecosystem.
- cesium-mcp — AI control for CesiumJS 3D globe
- openlayers-mcp — AI control for OpenLayers
MIT