Openlayers Mcp

OpenLayers MCP

AI-Powered Map Control via Model Context Protocol for OpenLayers

Connect any MCP-compatible AI agent to OpenLayers — view, layers, features, styles, drawing, all through natural language.

中文文档

---

Architecture

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

Packages

| Package | Description | |---------|-------------| | [openlayers-mcp-runtime](packages/openlayers-mcp-runtime/) | MCP Server (stdio) — 30+ tools across 7 toolsets, WebSocket bridge to browser | | [openlayers-mcp-bridge](packages/openlayers-mcp-bridge/) | Browser SDK — receives commands via WebSocket and controls OpenLayers map |

Quick Start

1. Install & Build

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

2. Start the MCP Runtime

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

3. Connect Browser

Open examples/minimal/index.html in a browser. The bridge auto-connects to ws://localhost:9300.

Or integrate the bridge in your own app:

import { OpenLayersBridge } from 'openlayers-mcp-bridge'
import Map from 'ol/Map'
import View from 'ol/View'
import TileLayer from 'ol/layer/Tile'
import OSM from 'ol/source/OSM'

const map = new Map({
  target: 'map',
  layers: [new TileLayer({ source: new OSM() })],
  view: new View({ center: [0, 0], zoom: 2 })
})

const bridge = new OpenLayersBridge(map)
bridge.connect('ws://localhost:9300')

4. Connect AI Agent

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

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

Now ask your AI: "Show a map of Paris and add a polygon around the Louvre"

Usage Examples

Ask your AI agent natural language questions like:

• "Fly to Tokyo at zoom level 12"
• "Add a vector layer from this GeoJSON URL"
• "Draw a polygon on the map, then export it as GeoJSON"
• "Set the layer opacity to 50%"
• "Add a marker at the Eiffel Tower with a popup label"
• "Take a screenshot of the current map view"

30+ Available Tools

Tools are organized into 7 toolsets. Default mode enables 4 core toolsets. Use list_toolsets and enable_toolset to dynamically activate more.

| Toolset | Tools | Default | |---------|-------|---------| | view | flyTo, setView, getView, fitExtent, zoomIn, zoomOut | Yes | | layer | addTileLayer, addVectorLayer, removeLayer, listLayers, setLayerVisibility, setLayerOpacity, setLayerZIndex | Yes | | feature | addFeature, addGeoJSON, removeFeature, updateFeature, listFeatures | Yes | | interaction | screenshot, getFeatureAtPixel, getFeaturesInExtent | Yes | | overlay | addOverlay, removeOverlay, updateOverlay, listOverlays | No | | style | setFeatureStyle, setLayerStyle | No | | draw | enableDraw, disableDraw, getDrawnFeatures | 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 |

Why OpenLayers?

• Truly open source — BSD 2-Clause, no API key required for basic usage
• Projection support — native EPSG:4326, EPSG:3857, and custom CRS
• Massive ecosystem — WMS, WMTS, WFS, GeoJSON, KML, GeoTIFF, MVT, and more
• Mature and stable — 15+ years of development, used by governments and enterprises worldwide

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OL_MCP_PORT | 9300 | WebSocket server port | | OL_TOOLSETS | view,layer,feature,interaction | Comma-separated default toolsets |

Related Projects

• cesium-mcp — AI control for CesiumJS 3D globe
• mapbox-mcp — AI control for Mapbox GL JS

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/openlayers-mcp
• License: MIT

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