cesium-mcp

Usage statistics default to on. Runtime/Dev print a startup notice; browser integrations show a console notice. Set CESIUM_TELEMETRY_DISABLED=1 (Node), or globalThis.CESIUM_MCP_TELEMETRY_DISABLED=true before browser initialization. Fields, destination and opt-out.

[!IMPORTANT]

📣 作者正在求职 · 北京

AI 应用开发 · Agent 应用开发 · AI 产品全栈

我是高鹏彬，有约 6 年软件开发经验。如果你们团队正在招人，欢迎联系，也感谢帮忙内推或转发！

📄 查看简历 PDF　·　✉️ 联系我

查看我的项目与个人介绍 → · 邮箱：1804287165@qq.com

[!TIP] 📣 Built with Cesium MCP? / 谁在使用 Cesium MCP？

Share your project, screenshots, or feedback—work in progress is welcome! / 欢迎分享项目、截图和使用反馈，开发中的作品也欢迎！

Share / 分享 → Issue #44 · Discussion / 讨论区

---

Cesium Map in Codex

Install the hosted map plugin from this repository's Cesium Map Community source:

codex plugin marketplace add gaopengbin/cesium-mcp --ref main
codex plugin add cesium-map@cesium-community

Restart Codex and ask “Open a map of Manhattan.” Uses native host chat, with no local map server or separate model API key. Requires a compatible MCP Apps host. This is a community beta, separate from the OpenAI public directory.

Installation and compatibility · ZIP download · Product website

Continue in native Codex chat

• “Open the New York 3D city blocks scene, change the selected building height to 180 metres, then read it back.”
• “Explain the selected hexagon in the San Francisco city activity scene.”
• “Show the Los Angeles hotspots scene, then zoom in on the route.”

Select a scene in the map, click an object and choose Ask in Codex to continue with its map context. The host controls chat placement and map expansion.

Map previews

Actual running screenshot: the development preview is connected to the hosted HTTPS MCP service. The native conversation UI is provided by Codex; it is not pictured here.

San Francisco · City activity	New York · 3D city blocks	Los Angeles · Hotspots
Inspect feature values and change classification colors	Select buildings, edit extrusion heights and read back properties	Combine a heatmap, markers and connecting routes

These covers come from rendered map scenes. Buildings, activity values and heatmap points are demonstration data, not surveyed heights or official statistics. Basemap imagery: Esri and its imagery contributors.

Demo

https://github.com/user-attachments/assets/8a40565a-fcdd-47bf-ae67-bc870611c908

Packages & Entry Points

Module	Role	Status	Links
cesium-mcp-contracts	Transport-neutral names, descriptions, and JSON Schemas for browser tools	New shared layer	source
cesium-mcp-bridge	Protocol- and transport-free Cesium command executor (60+ commands)	Mainline, actively iterated	· source
cesium-mcp-webmcp	One-package Viewer integration plus the native document.modelContext adapter	Browser integration	source
examples/webmcp-integration	Focused npm + Vite integration without a chat UI or MCP server	Developer example	example
examples/browser-agent	Browser-only AI agent with automatic WebMCP exposure	Recommended	example · live demo
cesium-mcp-runtime	MCP server (stdio + HTTP)	Stable MCP SDK v2	· source
cesium-mcp-dev	CesiumJS API knowledge base for coding assistants	Maintained	· source

Which one? Personal project or quick try → browser-agent. Let a compatible browser agent discover page-local Cesium tools → WebMCP. Existing web app embedding an AI assistant → bridge + your own function calling. Calling from Claude Desktop / Cursor / Dify → MCP runtime.

Architecture

flowchart LR
  subgraph clients ["AI Drivers (pick one)"]
    BA["Browser Agent\n(in the same page)"]
    WM["WebMCP Agent\n(browser-provided)"]
    FC["Your web app\nfunction calling"]
    MCP["Claude / Cursor / Dify\nvia MCP runtime"]
  end

  CONTRACTS["cesium-mcp-contracts\ntool definitions"]
  WEBMCP["cesium-mcp-webmcp\nnative adapter"]

  subgraph core ["cesium-mcp-bridge (browser)"]
    B["60+ tools\nprotocol-agnostic dispatcher"]
    C["CesiumJS Viewer"]
  end

  CONTRACTS -.-> BA
  CONTRACTS -.-> WEBMCP
  BA -- "in-page call" --> B
  WM -- "document.modelContext" --> WEBMCP
  WEBMCP --> B
  FC -- "in-page call" --> B
  MCP -- "WebSocket / JSON-RPC" --> B
  B --> C

  style clients fill:#1e293b,stroke:#528bff,color:#e2e8f0
  style core fill:#1e293b,stroke:#12B76A,color:#e2e8f0

The bridge remains the execution core, while contracts and protocol adapters stay separate. Pick whichever driver matches your scenario — they all reach the same Cesium command layer. On WebMCP-capable browsers, cesium-mcp-webmcp can expose 61 browser-safe commands in 12 selectable toolsets through document.modelContext without adding an MCP transport or backend server.

Relationship to the CesiumGS AI ecosystem

CesiumGS's newer AI work is split between cesiumjs-ai-starter-app, a deployable application template, and cesiumjs-skills, development-time guidance for coding agents. The earlier cesium-ai-integrations repository contains the first-generation experiments and community contributions that helped explore this space.

cesium-mcp is an independent runtime and integration toolkit, not a continuation of the earlier WebSocket-only reference architecture. Its reusable Bridge and shared contracts work unchanged across browser-only function calling, native WebMCP, standard MCP over stdio/HTTP, and embedded desktop shells. A local WebSocket bridge is used only when an external MCP host needs to reach a live browser Viewer; it is not required for the hosted demo or page-local integrations.

The project author was an early contributor to CesiumGS/cesium-ai-integrations, contributing the Imagery server, Terrain server, and unified MCP Gateway. Those experiments informed this project's multi-protocol architecture, while the implementation, release lifecycle, and roadmap remain independent.

Quick Start

MCP Apps map panel

Open an interactive Cesium map inside a compatible MCP Apps host with openCesiumMap. The panel uses existing MCP tools, publishes camera/layer/selection context, and can send a selected object to the conversation. OpenAI global/thread entrypoint metadata is included; availability depends on the host.

Try the local preview with npm run app:preview -w packages/cesium-mcp-runtime after npm ci and npm run build, then open http://127.0.0.1:19311/. See the MCP Apps guide for host configuration and verification boundaries.

Path 0 — Try in 30 seconds (browser agent, recommended)

Open the live demo and ask—the hosted model is ready without a browser API key:

"Fly to the Eiffel Tower and drop a red marker"

Fork the examples/browser-agent folder to deploy your own.

Path 1 — Expose Cesium tools through WebMCP (Chrome 149+ experimental)

The browser-agent example automatically registers all 61 browser-safe page tools plus 3 page-local resource tools when document.modelContext is available. Its built-in chat uses automatic toolset routing while keeping resource handles available for large GeoJSON/CZML inputs, and still offers explicit core, single-toolset, and all-tools modes:

npm run build -w packages/cesium-mcp-bridge
npm run build -w packages/cesium-mcp-webmcp
npx serve . -l 4173