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?.

MCP Apps map panel

openCesiumMap serves an interactive Cesium Viewer through the standard ui://cesium-mcp/map-v10.html MCP Apps resource. The map occupies the primary area and uses the host's existing native chat through ui/message, with no duplicate composer or history. Layout and host theme/locale changes preserve the Viewer, selection and session. The app follows host semantic style variables and fonts, supports Chinese and English, and publishes camera, layers and selected-object context. Local preview controls simulate live host settings and record message delivery. OpenAI global/thread entrypoint and fullscreen hints are included.

The built HTML, embedded Worker graph and Bridge bundle ship in dist. A compatible host must support WebGL and Blob module workers in an isolated, stable UI origin. The embedded panel exchanges commands through app-only MCP tools and does not access a local WebSocket. CESIUM_APP_DOMAIN optionally declares a dedicated UI origin. External browser Viewers retain the existing WebSocket transport.

For a real local MCP Apps preview, run npm run app:preview -w packages/cesium-mcp-runtime from a built repository and open http://127.0.0.1:19311/. See the full guide. Client-specific ChatGPT installation is a separate verification step.

Vector tiles

Enable the tiles toolset with CESIUM_TOOLSETS=view,entity,layer,interaction,tiles or enable_toolset. Use loadVectorTiles for MVT /{z}/{x}/{y} URLs or vector 3D Tiles, click a feature and read getSelectedTileFeature, then update its managed layer using updateLayerStyle with tileStyle.color and tileStyle.lineWidth. Read back getLayerSchema.metadata.tileStyle to verify the applied expressions.

Vector rendering and clamping require CesiumJS 1.145. Clamped line/polygon picking uses an experimental bounded adapter. For external data in an MCP Apps panel, configure exact allowed origins with CESIUM_MAP_DATA_ORIGINS. See the vector tiles guide for source formats, styling and limits.

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.

The npm package ships its browser Bridge bundle locally. The built-in Viewer at http://localhost:9100/ therefore does not depend on an unpkg fallback; CesiumJS itself is still loaded from the official Cesium CDN.

For ordinary MCP users this is a one-package setup: run cesium-mcp-runtime and use the built-in Viewer. Install cesium-mcp-bridge separately only when developing a custom CesiumJS page.

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 -y cesium-mcp-runtime

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

Then open http://localhost:9100/ to use the built-in Viewer. No separate Bridge installation is required for this default path.

Streamable HTTP Mode

For remote/cloud MCP clients like Dify:

# Start in HTTP transport mode
npx -y 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 -y cesium-mcp-runtime

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

MCP Client Configuration

Network access

Runtime binds to 127.0.0.1 by default, including its HTTP and WebSocket ports. Local native MCP clients and pages served from localhost continue to work. Pages opened directly as file:// must instead be served by a local HTTP server.

Variable	Purpose
CESIUM_HOST	Bind address, default 127.0.0.1. Non-loopback addresses require CESIUM_AUTH_TOKEN.
CESIUM_AUTH_TOKEN	Shared connection secret. When set, all APIs and WebSocket connections require authentication, including local clients.
CESIUM_ALLOWED_HOSTS	Comma-separated exact hostnames without ports, in addition to loopback and the bind address. No wildcards.
CESIUM_ALLOWED_ORIGINS	Comma-separated exact HTTPS page origins. Loopback HTTP/HTTPS origins are allowed by default. No wildcards.

For remote access, use HTTPS/WSS through a reverse proxy and configure the public hostname and Viewer origin explicitly. For example, set CESIUM_HOST=0.0.0.0, CESIUM_ALLOWED_HOSTS=maps.example.com, CESIUM_ALLOWED_ORIGINS=https://maps.example.com, and a generated CESIUM_AUTH_TOKEN in the server environment. Preserve the public Host header and WebSocket upgrades in the proxy.

MCP HTTP and REST clients send Authorization: Bearer <token>. The built-in Viewer asks for the connection token when authentication is enabled; it keeps the token in the page only. Custom browser bridges authenticate with WebSocket subprotocols:

const encoded = btoa(String.fromCharCode(...new TextEncoder().encode(token)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
const ws = new WebSocket('wss://maps.example.com/?session=demo', [
  'cesium-mcp', `cesium-token.${encoded}`,
])

Do not put credentials in query strings. Reverse proxies must not log Authorization or Sec-WebSocket-Protocol headers. The Viewer HTML and Bridge script are public assets; protected APIs and WebSocket upgrades still require the token. Secondary local Runtime instances must use the same token to relay to an existing instance. Browser session IDs select a Viewer; they are not credentials.

Claude Desktop

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

VS Code (Copilot)

In .vscode/mcp.json:

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

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "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, input validation, advertised output schemas, and structured results are generated from the canonical JSON Schemas in cesium-mcp-contracts. Tool calls also retain text content for older clients.

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": ["-y", "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

1. sessionId in tool parameters (explicit per-call override)
2. ?session=xxx in MCP HTTP URL (connection-level)
3. DEFAULT_SESSION_ID environment variable
4. 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.

Resource Handles

The runtime always registers storeResource, listResources, and deleteResource. Store large GeoJSON or CZML once, then pass the returned resourceId to addGeoJsonLayer, addGeoJsonPrimitive, addLabel, addHeatmap, or loadCzml.

Resources are isolated by the same browser sessionId used for command routing. They expire after 30 minutes by default and are never forwarded to the browser until a consuming tool resolves the handle. Existing inline data and remote url inputs remain compatible.

See the resource handle guide.

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.145.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