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.

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

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 . 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)*

| addCorridor | Add a corrido