Getting Started

This guide configures the Node.js MCP runtime for desktop clients and workflow platforms. To expose tools directly inside a compatible browser without running an MCP service, follow the WebMCP browser integration guide.

Prerequisites

• Node.js 22 or higher
• A CesiumJS application (or use our minimal example)
• An MCP-compatible AI client (Claude Desktop, VS Code Copilot, Cursor, etc.)

Installation

MCP 2026-07-28 preview

cesium-mcp-runtime@1.143.4-next.0 is available on npm under the next tag. It supports existing MCP 2025-11-25 clients and the new 2026-07-28 protocol from the same stdio/HTTP entry. The stable latest tag remains on 1.143.3.

npm install cesium-mcp-bridge@next
npx cesium-mcp-runtime@next

Remove @next to return to the stable channel.

1. Add the Bridge to Your CesiumJS App

npm install cesium-mcp-bridge

Initialize the bridge after creating your Cesium Viewer:

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

const viewer = new Cesium.Viewer('cesiumContainer')
const bridge = new CesiumBridge(viewer)

2. Start the MCP Runtime

stdio mode (for Claude Desktop, VS Code, Cursor):

npx cesium-mcp-runtime

HTTP mode (for Dify, n8n, and other HTTP-based AI platforms):

npx cesium-mcp-runtime --transport http --port 3211

This starts a Node.js process that:

• Exposes MCP tools on the selected transport (stdio or HTTP)
• Opens a WebSocket server on port 9100 (for the browser bridge)

To run the MCP v2 preview in either mode, append @next to the package name:

npx cesium-mcp-runtime@next
npx cesium-mcp-runtime@next --transport http --port 3211

3. Configure Your AI Agent

Claude Desktop

Edit claude_desktop_config.json:

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

VS Code (GitHub Copilot)

Create .vscode/mcp.json:

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

Cursor

Create .cursor/mcp.json:

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

For the preview channel, use "cesium-mcp-runtime@next" as the last argument in any of the client configurations above.

Dify / n8n (HTTP transport)

Start the runtime in HTTP mode first:

npx cesium-mcp-runtime --transport http --port 3211

Then in Dify, add an MCP tool node with:

{
  "cesium-mcp": {
    "transport": "streamable_http",
    "url": "http://localhost:3211/mcp",
    "timeout": 60
  }
}

For Docker-hosted Dify, replace localhost with host.docker.internal. See the full guide: examples/dify-integration/

4. Try It Out

Open your CesiumJS app in a browser, then ask your AI agent:

"Fly to the Eiffel Tower"

The agent will call the flyTo tool, which routes through the runtime to the bridge, and your globe will animate to Paris.

IDE-Only Setup (cesium-mcp-dev)

If you just want AI-powered CesiumJS code assistance (no live globe), install the dev server:

npx cesium-mcp-dev

This provides:

• API documentation lookup — query Cesium classes, methods, properties
• Code snippet generation — get working code for common patterns
• Entity template builder — generate Entity configurations from descriptions

Configure it the same way as the runtime, replacing cesium-mcp-runtime with cesium-mcp-dev.

Environment Variables

Variable	Default	Description
CESIUM_WS_PORT	9100	WebSocket server port
DEFAULT_SESSION_ID	default	Session ID for multi-tab routing
MCP_TRANSPORT	stdio	Transport mode: stdio or http
MCP_HTTP_PORT	3211	HTTP server port (when MCP_TRANSPORT=http)
HTTPS_PROXY	—	HTTP proxy URL for geocode requests (e.g. http://127.0.0.1:10808)
OSM_USER_AGENT	cesium-mcp-runtime/1.0	User-Agent for Nominatim geocode API
CESIUM_LOCALE	en	Tool description language: en (English, default) or zh-CN (Chinese)

Proxy Configuration

The geocode tool calls the Nominatim API over HTTPS. If you need a proxy (e.g. in China), set HTTPS_PROXY in your MCP client config:

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:10808"
      }
    }
  }
}

Supported variables: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY. The runtime uses Node.js built-in undici.ProxyAgent — no extra dependencies needed.

Minimal Example

A complete single-file example is included in the repository:

git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp/examples/minimal
# Open index.html in a browser

This example includes a CesiumJS Viewer with the bridge pre-configured, ready for AI agent control.

Next Steps

• Architecture — understand the shared execution and adapter layers
• WebMCP Browser Integration — expose page-local tools without an MCP server
• Bridge API — all 60 browser commands
• Runtime API — MCP tools and resources
• Dev API — IDE coding assistance tools