Cesium Mcp Runtime

cesium-mcp-runtime

Usage statistics are on by default, with a startup notice on stderr. Set CESIUM_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1, or pass --no-telemetry to disable. Collected fields and privacy.

English | 中文

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

[npm version] [license]

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.147. 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:

Install & Run

# Stable channel (stdio mode, default)npx -y cesium-mcp-runtime
# Or install globallynpm install -g cesium-mcp-runtimecesium-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 modenpx -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.

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 Configuration

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

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:

View

Entity

Layer

Camera (toolset: camera)

Extended Entity Types (toolset: entity-ext)

Animation (toolset: animation)

Tiles & Data (toolset: tiles)

Interaction (toolset: interaction)

Other

MCP Resources

Environment Variables

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=geoagentTab 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

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