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	MCP Server (stdio) — 30+ tools across 7 toolsets, WebSocket bridge to browser
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

openlayers-mcp