gaopengbin/cesium-mcp

---

Demo

https://github.com/user-attachments/assets/8a40565a-fcdd-47bf-ae67-bc870611c908

Packages & Entry Points

Module	Role	Status	Links
cesium-mcp-contracts	Transport-neutral names, descriptions, and JSON Schemas for browser tools	New shared layer	source
cesium-mcp-bridge	Protocol- and transport-free Cesium command executor (60+ commands)	Mainline, actively iterated	· source
cesium-mcp-webmcp	Native document.modelContext adapter for Cesium tool contracts	New browser adapter	source
examples/webmcp-integration	Focused npm + Vite integration without a chat UI or MCP server	Developer example	example
examples/browser-agent	Browser-only AI agent with automatic WebMCP exposure	Recommended	example · live demo
cesium-mcp-runtime	MCP server (stdio + HTTP)	Stable + MCP v2 preview	· source
cesium-mcp-dev	CesiumJS API knowledge base for coding assistants	Maintained	· source

Which one? Personal project or quick try → browser-agent. Let a compatible browser agent discover page-local Cesium tools → WebMCP. Existing web app embedding an AI assistant → bridge + your own function calling. Calling from Claude Desktop / Cursor / Dify → MCP runtime.

Architecture

flowchart LR
  subgraph clients ["AI Drivers (pick one)"]
    BA["Browser Agent\n(in the same page)"]
    WM["WebMCP Agent\n(browser-provided)"]
    FC["Your web app\nfunction calling"]
    MCP["Claude / Cursor / Dify\nvia MCP runtime"]
  end

  CONTRACTS["cesium-mcp-contracts\ntool definitions"]
  WEBMCP["cesium-mcp-webmcp\nnative adapter"]

  subgraph core ["cesium-mcp-bridge (browser)"]
    B["60+ tools\nprotocol-agnostic dispatcher"]
    C["CesiumJS Viewer"]
  end

  CONTRACTS -.-> BA
  CONTRACTS -.-> WEBMCP
  BA -- "in-page call" --> B
  WM -- "document.modelContext" --> WEBMCP
  WEBMCP --> B
  FC -- "in-page call" --> B
  MCP -- "WebSocket / JSON-RPC" --> B
  B --> C

  style clients fill:#1e293b,stroke:#528bff,color:#e2e8f0
  style core fill:#1e293b,stroke:#12B76A,color:#e2e8f0

The bridge remains the execution core, while contracts and protocol adapters stay separate. Pick whichever driver matches your scenario — they all reach the same Cesium command layer. On WebMCP-capable browsers, cesium-mcp-webmcp can expose 61 browser-safe commands in 12 selectable toolsets through document.modelContext without adding an MCP transport or backend server.

Quick Start

Path 0 — Try in 30 seconds (browser agent, recommended)

Open the live demo and ask—the hosted model is ready without a browser API key:

"Fly to the Eiffel Tower and drop a red marker"

Fork the examples/browser-agent folder to deploy your own.

Path 1 — Expose Cesium tools through WebMCP (Chrome 149+ experimental)

The browser-agent example automatically registers all 61 browser-safe page tools when document.modelContext is available. Its built-in chat uses automatic toolset routing to keep each normal request at 20 tools or fewer, while still offering explicit core, single-toolset, and all-61 modes:

npm run build -w packages/cesium-mcp-bridge
npm run build -w packages/cesium-mcp-webmcp
npx serve . -l 4173

Open http://localhost:4173/examples/browser-agent/, click Start, then inspect or execute the tools in DevTools → Application → WebMCP. Enable #enable-webmcp-testing and #devtools-webmcp-support in chrome://flags for local testing.

Application developers install the adapter separately. End users only open the integrated website; they do not install npm packages or run an MCP server.

npm install cesium cesium-mcp-bridge cesium-mcp-webmcp

import { CesiumBridge } from 'cesium-mcp-bridge'
import { registerCesiumWebMcp } from 'cesium-mcp-webmcp'

const bridge = new CesiumBridge(viewer)
const registration = await registerCesiumWebMcp(bridge, {
  toolsets: 'all',
  excludeTools: ['geocode'], // add your own browser geocoder to expose this tool
})

// Later, if the page is unmounted:
registration.unregister()

See the WebMCP adapter API for custom integrations. For a complete npm + Vite application, start from the WebMCP integration example.

Path 2 — Embed in your own web app (function calling)

npm install cesium-mcp-bridge

import { CesiumBridge } from 'cesium-mcp-bridge';

const bridge = new CesiumBridge(viewer);
// Then: send the bridge's tool schema to any LLM that supports function/tool calling,
// route the model's tool calls to bridge.execute(name, params).

See examples/browser-agent/index.html for a complete loop with OpenAI-compatible APIs.

Path 3 — Use from Claude Desktop / Cursor / Dify (MCP)

Install bridge as in Path 2, then start the MCP runtime:

# Stable channel — npm latest (1.143.3)
npx cesium-mcp-runtime

# MCP v2 preview — npm next (1.143.4-next.0)
npx cesium-mcp-runtime@next

# HTTP mode; add @next to use the preview
npx cesium-mcp-runtime --transport http --port 3000
npx cesium-mcp-runtime@next --transport http --port 3000

The next preview serves existing MCP 2025-11-25 clients and the new 2026-07-28 protocol from the same stdio/HTTP entry. It uses the stable TypeScript SDK v2 and has passed the official server-stateless conformance scenario (28/28). The npm latest tag remains on 1.143.3, so you can switch back by removing @next. For matching preview package versions, install cesium-mcp-bridge@next in the browser application.

MCP client config:

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

To test the preview from an MCP client, change the last argument to "cesium-mcp-runtime@next".

62 Available Command Tools

Tools are organized into 12 toolsets. Default mode enables 4 core toolsets (30 tools). Set CESIUM_TOOLSETS=all for everything, or let the AI discover and activate toolsets dynamically at runtime.

Canonical contracts: Tool descriptions default to English; set CESIUM_LOCALE=zh-CN for Chinese. Titles, behavior annotations, localized descriptions, defaults, and Runtime input validation all come from the shared JSON Schemas in cesium-mcp-contracts.

Toolset	Tools
view (default)	flyTo, setView, getView, zoomToExtent, saveViewpoint, loadViewpoint, listViewpoints, exportScene
entity (default)	addMarker, addLabel, addModel, addPolygon, addPolyline, updateEntity, removeEntity, batchAddEntities, queryEntities, getEntityProperties
layer (default)	addGeoJsonLayer, addGeoJsonPrimitive, listLayers, removeLayer, clearAll, setLayerVisibility, updateLayerStyle, getLayerSchema, setBasemap
interaction (default)	screenshot, highlight, measure
camera	lookAtTransform, startOrbit, stopOrbit, setCameraOptions
entity-ext	addBillboard, addBox, addCorridor, addCylinder, addEllipse, addRectangle, addWall
animation	createAnimation, controlAnimation, removeAnimation, listAnimations, updateAnimationPath, trackEntity, controlClock, setGlobeLighting
tiles	load3dTiles, load3dGaussianSplat, loadTerrain, loadImageryService, loadCzml, loadKml, setEdgeDisplayMode
trajectory	playTrajectory
heatmap	addHeatmap
scene	setSceneOptions, setPostProcess, setIonToken (Runtime only)
geolocation	geocode

Relationship with CesiumGS official MCP servers: The camera, entity-ext, and animation toolsets natively fuse capabilities from CesiumGS/cesium-mcp-server (Camera Server, Entity Server, Animation Server) into this project's unified bridge architecture. This means you get all official functionality plus additional tools — in a single MCP server, without running multiple processes.

Examples

See examples/minimal/ for a complete working demo.

Development

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

Version Policy

Version format: {CesiumMajor}.{CesiumMinor}.{MCPPatch}

Segment	Meaning	Example
1.143	Tracks CesiumJS version — built & tested against Cesium ~1.143.0	1.143.0 → Cesium 1.143
.x	MCP patch — independent iterations for new tools, bug fixes, docs	1.143.0 → 1.143.1

Official CesiumJS releases are reviewed before the compatibility baseline is bumped; the project does not automatically claim support for a newer release without Bridge verification.

Related Projects

• mapbox-mcp — AI control for Mapbox GL JS
• openlayers-mcp — AI control for OpenLayers

Star History

License

MIT