cesium-mcp-runtime

cesium-mcp-runtime

English | 中文

MCP Server that enables AI Agents to control a Cesium globe in real-time via the Model Context Protocol.

Release channel: latest uses the stable MCP SDK v2 and supports both MCP 2025-11-25 and 2026-07-28 from the same stdio/HTTP entry. If you only want to try the "AI + Cesium" feel, examples/browser-agent is the recommended starting point — zero backend, runs in three minutes. See Which mode should I use?.

Architecture

AI Agent <--MCP stdio--> cesium-mcp-runtime <--WebSocket--> Browser (cesium-mcp-bridge)
AI Agent <--MCP HTTP---> cesium-mcp-runtime <--WebSocket--> Browser (cesium-mcp-bridge)

The runtime acts as a bridge between MCP-compatible AI clients (Claude Desktop, VS Code Copilot, Cursor, etc.) and a browser running CesiumJS. It translates MCP tool calls into WebSocket commands that cesium-mcp-bridge executes.

Two transport modes are supported:

Transport	Use Case	Protocol
stdio (default)	Local AI clients (Claude Desktop, VS Code, Cursor)	Standard I/O
http	Remote/cloud MCP clients (Dify, custom backends)	Streamable HTTP

Install & Run

# Stable channel (stdio mode, default)
npx cesium-mcp-runtime

# Or install globally
npm install -g cesium-mcp-runtime
cesium-mcp-runtime

Streamable HTTP Mode

For remote/cloud MCP clients like Dify:

# Start in HTTP transport mode
npx cesium-mcp-runtime --transport http --port 3000

# MCP endpoint: POST http://localhost:3000/mcp

Environment variable alternative:

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx cesium-mcp-runtime

In HTTP mode, all 62 Cesium command tools are enabled by default (no dynamic toolset discovery needed).

MCP Client Configuration

Claude Desktop

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["cesium-mcp-runtime"],
      "env": {
        "CESIUM_WS_PORT": "9100",
        "DEFAULT_SESSION_ID": "default"
      }
    }
  }
}

VS Code (Copilot)

In .vscode/mcp.json:

{
  "servers": {
    "cesium": {
      "command": "npx",
      "args": ["cesium-mcp-runtime"],
      "env": {
        "DEFAULT_SESSION_ID": "default"
      }
    }
  }
}

Cursor

In .cursor/mcp.json:

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

MCP Tools (62 command tools + 2 discovery meta-tools)

Tools are organized into 12 toolsets. By default, 4 core toolsets are enabled (30 tools). Additional toolsets can be activated via environment variable or dynamically by the AI agent at runtime. Shared titles, behavior annotations, localized descriptions, defaults, and input validation are generated from the canonical JSON Schemas in cesium-mcp-contracts.

Toolsets Overview

Toolset	Tools	Default	Description
view	8	Yes	Camera view controls + viewpoint bookmarks + scene export
entity	10	Yes	Core entity operations + batch, query & property inspection
layer	9	Yes	Layer management (GeoJSON, schema, style, basemap)
interaction	3	Yes	Screenshot, highlight & measurement
camera	4	—	Advanced camera controls (orbit, lookAt)
entity-ext	7	—	Extended entity types (box, cylinder, wall, etc.)
animation	8	—	Animation system (waypoints, clock, tracking, lighting)
tiles	7	—	3D Tiles, Gaussian Splats, terrain, imagery services, CZML & KML
trajectory	1	—	Trajectory playback
heatmap	1	—	Heatmap visualization
scene	3	—	Scene options, post-processing & Runtime-only Ion credentials
geolocation	1	—	Geocoding — convert address/place name to coordinates (Nominatim/OSM)

Toolset Configuration

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["cesium-mcp-runtime"],
      "env": {
        "CESIUM_TOOLSETS": "all"
      }
    }
  }
}

CESIUM_TOOLSETS value	Result
(not set)	Default 4 toolsets (30 tools + 2 meta-tools)
view,entity,camera,animation	Only specified toolsets + 2 meta-tools
all	All 62 command tools, no meta-tools

Dynamic Discovery (meta-tools)

When not in all mode, two meta-tools are always available so the AI can discover and activate additional capabilities on demand:

Tool	Description
list_toolsets	List all toolset groups with enabled status and tool names
enable_toolset	Dynamically enable a toolset — new tools become immediately available

View

Tool	Description
flyTo	Fly to coordinates (lon, lat, height, heading, pitch, roll, duration)
setView	Set camera position instantly
getView	Get current camera state
zoomToExtent	Zoom to bounding box (west, south, east, north)

Entity

Tool	Description
addMarker	Add a marker at coordinates
addLabel	Add text labels to the map
addModel	Add 3D model (glTF/GLB or Ion asset)
addPolygon	Add polygon with styling
addPolyline	Add polyline with styling
updateEntity	Update entity properties
removeEntity	Remove entity by ID

Layer

Tool	Description
addGeoJsonLayer	Add GeoJSON with styling (choropleth, category, etc.)
listLayers	List all layers
removeLayer	Remove layer by ID
setLayerVisibility	Toggle layer visibility
updateLayerStyle	Change layer color/opacity/width
setBasemap	Switch basemap

Camera (toolset: camera)

Tool	Description
lookAtTransform	Orbit-style camera aim at a position (heading/pitch/range)
startOrbit	Start orbiting the camera around current center
stopOrbit	Stop orbit animation
setCameraOptions	Configure camera controller (enable/disable rotation, zoom, tilt)

Extended Entity Types (toolset: entity-ext)

Tool	Description
addBillboard	Add an image icon at a position
addBox	Add a 3D box with dimensions and material
addCorridor	Add a corridor (path with width)
addCylinder	Add a cylinder or cone
addEllipse	Add an ellipse (oval)
addRectangle	Add a rectangle by geographic bounds
addWall	Add a wall along positions

Animation (toolset: animation)

Tool	Description
createAnimation	Create time-based animation with waypoints (moving entity along path)
controlAnimation	Play or pause the current animation
removeAnimation	Remove an animation entity
listAnimations	List all active animations
updateAnimationPath	Update animation path visual properties
trackEntity	Follow an entity with the camera
controlClock	Configure Cesium clock (time range, speed, animation state)
setGlobeLighting	Enable/disable globe lighting and atmospheric effects

Tiles & Data (toolset: tiles)

Tool	Description
load3dTiles	Load 3D Tiles from URL or Ion asset ID
loadTerrain	Set terrain provider
loadImageryService	Add imagery service (WMS/WMTS/XYZ/Ion)

Interaction (toolset: interaction)

Tool	Description
screenshot	Capture map as base64 PNG
highlight	Highlight layer features

Other

Tool	Toolset	Description
playTrajectory	trajectory	Animate entity along coordinate path
addHeatmap	heatmap	Generate heatmap from point data

MCP Resources

URI	Description
cesium://scene/camera	Current camera position, heading, pitch, roll
cesium://scene/layers	List of all loaded layers with types and visibility

Environment Variables

Variable	Default	Description
CESIUM_WS_PORT	9100	WebSocket server port
DEFAULT_SESSION_ID	default	Preferred browser session for MCP tool routing
CESIUM_TOOLSETS	(not set)	Toolset activation: omit for defaults, all for everything, or comma-separated list
CESIUM_LOCALE	en	Tool description language: en (English, default) or zh-CN (Chinese)
MCP_TRANSPORT	stdio	MCP transport mode: stdio or http
MCP_HTTP_PORT	(auto)	HTTP port for Streamable HTTP mode (default: CESIUM_WS_PORT + 100)

Browser-Side Setup

Your browser page needs to connect to the runtime via WebSocket and relay commands to cesium-mcp-bridge:

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

const bridge = new CesiumBridge(viewer)
const ws = new WebSocket('ws://localhost:9100?session=default')

ws.onmessage = async (event) => {
  const { id, method, params } = JSON.parse(event.data)
  try {
    const result = await bridge.execute({ action: method, params })
    ws.send(JSON.stringify({ id, result }))
  } catch (error) {
    ws.send(JSON.stringify({ id, error: { message: String(error) } }))
  }
}

Session Routing

Multiple browser tabs can connect to a single runtime using different session IDs:

Tab A: ws://localhost:9100?session=geoagent
Tab B: ws://localhost:9100?session=demo

Routing via MCP URL (recommended for Dify / third-party integrations)

Add ?session=xxx to the MCP HTTP endpoint URL:

http://localhost:3216/mcp?session=geoagent

All tool calls from that connection are automatically routed to the matching browser — no need to inject sessionId into prompts or tool parameters.

Routing priority

• sessionId in tool parameters (explicit per-call override)
• ?session=xxx in MCP HTTP URL (connection-level)
• DEFAULT_SESSION_ID environment variable
• First connected browser (fallback)

Explicit routing is fail-closed: when a tool parameter or MCP URL names a session that is missing or disconnected, the call returns an error instead of running against another Viewer. The default/first-connected fallback applies only when the caller did not explicitly select a session. Pending responses are also accepted only from the browser that received the command, and are rejected immediately if that browser disconnects.

HTTP Push API

The runtime also exposes an HTTP endpoint for non-MCP integrations (e.g., FastAPI backend):

curl -X POST http://localhost:9100/push \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "default", "command": {"action": "flyTo", "params": {"longitude": 116.39, "latitude": 39.91}}}'

Compatibility

Channel	Runtime	Bridge	MCP protocol	Cesium
latest	current stable	matching stable	2025-11-25 + 2026-07-28	~1.143.0

The stable release serves both protocol generations from the same stdio/HTTP entry using @modelcontextprotocol/server and @modelcontextprotocol/node 2.0.0 packages.

The repository pins the official conformance runner separately and validates the 2026-07-28 server-stateless scenario with:

npm run test:conformance:mcp

Conformance-only diagnostic tools are enabled only for that command. They are not registered by normal stdio, HTTP, or browser-demo runtime startup.

License

MIT