cesium-mcp
A protocol-agnostic Cesium 3D map control server that lets an AI open a live interactive globe and command its camera, entities, layers, styles, and measurements.
Camera & views —
flyTo,setView,getView,zoomToExtent, plus save/load/list named viewpoints andexportScenesnapshots.Entities — add markers, labels, models, polygons, polylines; batch-add up to 1000; update position/appearance/extrusion, query by name/type/bbox, read properties, remove.
GeoJSON layers — load from inline data, URL, or a
resourceId; render as entities or Cesium primitives; inspect schema/fields; toggle visibility; remove;clearAll.Styling — thematic styles (choropleth, category, gradient, randomColor),
tileStyleexpressions for 3D Tiles/MVT, label/imagery/primitive style overrides.Basemaps — switch between dark, satellite, OSM, ArcGIS, light, Tianditu, and Amap styles, or supply a custom XYZ URL template.
Interaction — PNG
screenshot, feature/whole-layerhighlight, andmeasuredistance or area on the map.Large payloads —
storeResource/listResources/deleteResourceto pass GeoJSON/CZML/JSON once and reference it by compact ID with a TTL.Toolset discovery —
list_toolsetsandenable_toolsetto activate extra groups (camera, entity-ext, animation, tiles, trajectory, heatmap, scene, geolocation) at runtime.Multi-browser routing — every command accepts an optional
sessionId;listSessionsshows connected viewers.MCP Apps panel —
openCesiumMapopens an embedded interactive map beside the chat (internal connect/exchange/disconnect transport tools support it).Tool annotations — each tool declares read-only/idempotent/destructive hints and typed input/output JSON schemas for safe model use.
Enables AI-powered control of CesiumJS 3D globes, allowing for camera manipulation, management of layers and markers, spatial analysis, and scene interaction through natural language commands.
Usage statistics default to on. Runtime/Dev print a startup notice; browser integrations show a console notice. Set
CESIUM_TELEMETRY_DISABLED=1(Node), orglobalThis.CESIUM_MCP_TELEMETRY_DISABLED=truebefore browser initialization. Fields, destination and opt-out.
📣 作者正在求职 · 北京
AI 应用开发 · Agent 应用开发 · AI 产品全栈
我是高鹏彬,有约 6 年软件开发经验。如果你们团队正在招人,欢迎联系,也感谢帮忙内推或转发!
📄 查看简历 PDF · ✉️ 联系我
📣 Built with Cesium MCP? / 谁在使用 Cesium MCP?
Share your project, screenshots, or feedback—work in progress is welcome! / 欢迎分享项目、截图和使用反馈,开发中的作品也欢迎!
Related MCP server: QGIS MCP
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-communityRestart 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 | |
cesium-mcp-bridge | Protocol- and transport-free Cesium command executor (60+ commands) | Mainline, actively iterated |
|
cesium-mcp-webmcp | One-package Viewer integration plus the native | Browser integration | |
examples/webmcp-integration | Focused npm + Vite integration without a chat UI or MCP server | Developer example | |
examples/browser-agent | Browser-only AI agent with automatic WebMCP exposure | Recommended | |
cesium-mcp-runtime | MCP server (stdio + HTTP) | Stable MCP SDK v2 |
|
cesium-mcp-dev | CesiumJS API knowledge base for coding assistants | Maintained |
|
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:#e2e8f0The 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 4173Open http://localhost:4173/examples/browser-agent/, click Start, then inspect or execute the tools in DevTools → Application → WebMCP. Enable #enable-webmcp-testing and #devtools-webmcp-support in chrome://flags for local testing.
Application developers install the adapter separately. End users only open the integrated website; they do not install npm packages or run an MCP server.
npm install cesium-mcp-webmcpimport { registerCesiumViewerWebMcp } from 'cesium-mcp-webmcp/viewer'
const registration = await registerCesiumViewerWebMcp(viewer, {
toolsets: 'all',
excludeTools: ['geocode'], // add your own browser geocoder to expose this tool
})
// Later, if the page is unmounted:
registration.unregister()See the WebMCP adapter API for custom integrations. For a complete npm + Vite application, start from the WebMCP integration example.
Path 2 — Embed in your own web app (function calling)
npm install cesium-mcp-bridgeimport { CesiumBridge } from 'cesium-mcp-bridge';
const bridge = new CesiumBridge(viewer);
// Then: send the bridge's tool schema to any LLM that supports function/tool calling,
// route the model's tool calls to bridge.execute(name, params).See examples/browser-agent/index.html for a complete loop with OpenAI-compatible APIs.
Path 3 — Use from Claude Desktop / Cursor / Dify (MCP)
Ordinary MCP users need only the Runtime package. It includes the browser Bridge bundle and a built-in Viewer at http://localhost:9100/; install cesium-mcp-bridge separately only when integrating a custom page.
# Stable channel — npm latest, MCP SDK v2
npx -y cesium-mcp-runtime
# HTTP mode
npx -y cesium-mcp-runtime --transport http --port 3000The stable release serves existing MCP 2025-11-25 clients and the new
2026-07-28 protocol from the same stdio/HTTP entry. It uses the stable
TypeScript SDK v2 and passes the official server-stateless conformance
scenario (28/28).
MCP client config:
{
"mcpServers": {
"cesium": {
"command": "npx",
"args": ["-y", "cesium-mcp-runtime"]
}
}
}62 Available Command Tools
Tools are organized into 12 toolsets. Default mode enables 4 core toolsets (30 tools). Set CESIUM_TOOLSETS=all for everything, or let the AI discover and activate toolsets dynamically at runtime.
Canonical contracts: Tool descriptions default to English; set
CESIUM_LOCALE=zh-CNfor Chinese. Titles, behavior annotations, localized descriptions, defaults, input validation, MCP output schemas, and structured results all come from the shared JSON Schemas incesium-mcp-contracts. Textcontentremains available for older clients.
Toolset | Tools |
view (default) |
|
entity (default) |
|
layer (default) |
|
interaction (default) |
|
camera |
|
entity-ext |
|
animation |
|
tiles |
|
trajectory |
|
heatmap |
|
scene |
|
geolocation |
|
Examples
See examples/minimal/ for a complete working demo.
Development
git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp
npm install
npm run build
npm test
npm run test:contracts
npm run test:schema-compat
npm run test:routing
npm run test:model-tools
npm run eval:model-tools
npm run test:e2e:packedtest:contracts is the focused parity gate for MCP Runtime metadata, WebMCP registration, Function Calling definitions, provider Schema portability, and the 60-tool Bridge Executor Registry. Run test:schema-compat directly for actionable OpenAI, Azure, VS Code MCP, and WebMCP Schema diagnostics.
test:routing evaluates bilingual and multi-intent Browser Agent requests across all 12 toolsets, checking required-tool recall and the 20-tool automatic-routing budget.
test:model-tools verifies the provider-neutral multi-turn scoring harness. eval:model-tools performs a no-network routing preflight by default; add an explicit provider and --live to measure real tool choice, argument validity, and required-tool completion. See Model Tool Evaluation.
test:e2e:packed builds npm tarballs, installs them in a clean temporary project, opens the real Cesium Viewer, and verifies a Runtime-WebSocket-Bridge command round trip.
Version Policy
Version format: {CesiumMajor}.{CesiumMinor}.{MCPPatch}
Segment | Meaning | Example |
| Runtime/Bridge/Dev major.minor follows the verified CesiumJS |
|
| MCP patch — independent iterations for new tools, bug fixes, docs |
|
Official CesiumJS releases are reviewed before the compatibility baseline is bumped; the project does not automatically claim support for a newer release without Bridge verification.
Related Projects
mapbox-mcp — AI control for Mapbox GL JS
openlayers-mcp — AI control for OpenLayers
Community
This project recognizes LINUX DO as a community for open-source exchange, technical discussion, and developer feedback.
Star History
License
Available Tools
41 toolsaddGeoJsonLayerB
Add a styled GeoJSON Point, LineString, or Polygon layer. Returns { success, data: { id, name, type, visible, color, dataRefId? }, message? }; use id with highlight.
Inputs: id, url, data, name, +4 more. Returns: data, error, message, success
addGeoJsonPrimitiveB
Render GeoJSON as Cesium primitives for large browser datasets. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: id, url, data, name, +7 more. Returns: data, error, message, success
addLabelC
Add property-based text labels for GeoJSON features. Returns { success, data: { labelCount: integer }, message? }.
Inputs: field (required), data, style, sessionId, +1 more. Returns: data, error, message, success
addMarkerA
Add a point marker at geographic coordinates. Returns { success, data: { entityId }, message? }; keep entityId for removeEntity.
Inputs: latitude (required), longitude (required), id, size, +3 more. Returns: data, error, message, success
addModelA
Add a glTF or GLB model at geographic coordinates. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: url (required), latitude (required), longitude (required), roll, +6 more. Returns: data, error, message, success
addPolygonA
Draw a polygon area from geographic coordinate tuples. Returns { success, data: { entityId }, message? }; keep entityId for removeEntity.
Inputs: coordinates (required), color, label, opacity, +4 more. Returns: data, error, message, success
addPolylineA
Draw a path or route from geographic coordinate tuples. Returns { success, data: { entityId }, message? }; keep entityId for removeEntity.
Inputs: coordinates (required), color, label, width, +2 more. Returns: data, error, message, success
batchAddEntitiesC
Add multiple supported entities in one page operation. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: entities (required), sessionId. Returns: data, error, message, success
clearAllADestructiveIdempotent
Clear all layers, entities, animations, and trajectories from the scene. Returns { success, data: { removedLayers, removedEntities }, message? }.
Inputs: sessionId. Returns: data, error, message, success
connectCesiumMapD
Internal map app transport: connect.
Inputs: sessionId (required).
deleteResourceBDestructiveIdempotent
Delete one session-scoped resource by resourceId.
Inputs: resourceId (required), sessionId. Returns: removed
disconnectCesiumMapC
Internal map app transport: disconnect.
Inputs: token (required), sessionId (required).
enable_toolsetAIdempotent
Enable a tool group to make its tools available. Call list_toolsets first to see available groups.
Inputs: toolset (required).
exchangeCesiumMapD
Internal map app transport: exchange.
Inputs: token (required), sessionId (required), results.
exportSceneARead-onlyIdempotent
Export the current view, layer, and entity state as JSON. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: sessionId. Returns: data, error, message, success
flyToAIdempotent
Animate the camera to a geographic location. Use for visible navigation requested by the user. Returns { success: boolean, message?: string, error?: string }.
Inputs: latitude (required), longitude (required), pitch, height, +3 more. Returns: error, message, success
getEntityPropertiesARead-onlyIdempotent
Read the properties and graphics metadata for one entity. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: entityId (required), sessionId. Returns: data, error, message, success
getLayerSchemaARead-onlyIdempotent
Inspect fields, entity counts, and metadata for a layer. For vector/3D Tiles, metadata.tileStyle returns the applied style expressions. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: layerId (required), sessionId. Returns: data, error, message, success
getSelectedTileFeatureARead-onlyIdempotent
Read the last clicked managed vector/3D Tiles feature attributes and layerId. Use updateLayerStyle with that layerId to style it. Returns feature=null when nothing is selected; metadata is a snapshot, not a whole-dataset query. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: sessionId. Returns: data, error, message, success
getViewARead-onlyIdempotent
Get the current camera position and orientation. Returns { success, data: { longitude, latitude, height, heading, pitch, roll }, message? }.
Inputs: sessionId. Returns: data, error, message, success
highlightAIdempotent
Highlight one feature or every feature in a GeoJSON layer. Returns { success: boolean, message?: string, error?: string }.
Inputs: clear, color, layerId, sessionId, +1 more. Returns: error, message, success
listLayersARead-onlyIdempotent
List all layers currently managed by the page. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: sessionId. Returns: data, error, message, success
listResourcesARead-onlyIdempotent
List resource metadata for the current browser or MCP session without returning payloads.
Inputs: sessionId. Returns: resources
listSessionsARead-onlyIdempotent
List all connected browser sessions (ID and connection state) for multi-browser routing
Inputs: no named parameters.
list_toolsetsARead-onlyIdempotent
List all available tool groups and their enabled status. Call this to discover additional capabilities before asking the user to configure anything.
Inputs: no named parameters.
listViewpointsARead-onlyIdempotent
List camera viewpoints saved in the current page. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: sessionId. Returns: data, error, message, success
loadViewpointAIdempotent
Restore a previously saved page-local camera state. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: name (required), duration, sessionId. Returns: data, error, message, success
measureA
Measure distance or area between geographic coordinate tuples. Returns { success, data: { mode, value, unit, segments?, id? }, message? }.
Inputs: mode (required), positions (required), id, sessionId, +1 more. Returns: data, error, message, success
openCesiumMapCesium MapARead-only
Open an interactive 3D map beside the conversation. Pass the returned sessionId to every map tool. Call once to open the map, then wait until its browser session connects before sending commands. Optionally reopen a known session.
Inputs: sessionId.
queryEntitiesARead-onlyIdempotent
Query page entities by name, type, or geographic extent. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: bbox, name, type, sessionId. Returns: data, error, message, success
removeEntityADestructiveIdempotent
Remove one entity created by an entity tool. Returns { success, message? } or { success: false, error } when entityId is not found.
Inputs: entityId (required), sessionId. Returns: error, message, success
removeLayerADestructiveIdempotent
Remove a managed layer from the page. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: id (required), sessionId. Returns: data, error, message, success
saveViewpointAIdempotent
Save the current camera state under a page-local name. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: name (required), sessionId. Returns: data, error, message, success
screenshotARead-onlyIdempotent
Capture the current Cesium map view as a PNG image. Returns { success, data: { dataUrl, width, height }, message? }; dataUrl is a base64 PNG.
Inputs: sessionId. Returns: data, error, message, success
setBasemapAIdempotent
Switch the visible basemap style. Returns { success, data: { basemap }, message? }.
Inputs: url, token, basemap, sessionId. Returns: data, error, message, success
setLayerVisibilityAIdempotent
Show or hide a managed layer. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: id (required), visible (required), sessionId. Returns: data, error, message, success
setViewAIdempotent
Set the camera position immediately without animation. Use for deterministic setup or instant view changes. Returns { success: boolean, message?: string, error?: string }.
Inputs: latitude (required), longitude (required), roll, pitch, +3 more. Returns: error, message, success
storeResourceA
Store GeoJSON, CZML, or JSON once and return a compact resourceId for later tool calls.
Inputs: data (required), kind (required), sessionId, resourceId, +1 more. Returns: kind, createdAt, expiresAt, sizeBytes, +1 more
updateEntityBIdempotent
Update the position, appearance, label, visibility, or polygon extrusion height of an entity, including data-source entities. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: entityId (required), show, color, label, +4 more. Returns: data, error, message, success
updateLayerStyleBIdempotent
Update vector, imagery, primitive, or 3D Tiles styling for a layer. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: layerId (required), sessionId, tileStyle, labelStyle, +3 more. Returns: data, error, message, success
zoomToExtentAIdempotent
Animate the camera to a west/south/east/north bounding box. Returns { success: boolean, data?: unknown, message?: string, error?: string }.
Inputs: bbox (required), duration, sessionId. Returns: data, error, message, success
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools target clearly distinct resources or actions, and descriptions distinguish similar operations such as entity vs. layer updates. However, addGeoJsonPrimitive vs. addGeoJsonLayer overlap in purpose, and exposed internal transport tools like connectCesiumMap/exchangeCesiumMap could be confused with openCesiumMap.
The set is predominantly consistent camelCase verb_noun naming (addMarker, updateLayerStyle, removeEntity, flyTo). Minor deviations include snake_case list_toolsets/enable_toolset and a few noun-only or verb-only names like screenshot, highlight, and measure.
At 41 tools, the surface is heavy for a single MCP server even though the Cesium map domain is broad. Several tools are internal transport or toolset-management utilities, which adds surface area beyond the core mapping workflow.
Coverage is broad: sessions, layers, resources, viewpoints, camera control, entity CRUD, styling, measurement, screenshots, basemap, export, and toolset discovery are all present. Minor gaps remain, notably no creation tools for animations/trajectories despite clearAll referencing them, and no import counterpart to exportScene.
Maintenance
Related MCP Connectors
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
Real-time planetary signal engine and Model Context Protocol (MCP) server for autonomous AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceEnables users to search for geographic locations and visualize them on an interactive 3D globe powered by CesiumJS and OpenStreetMap. It provides tools for geocoding addresses and rendering maps with specific bounding boxes through the Model Context Protocol.MIT
- AlicenseAqualityDmaintenanceConnect QGIS to Claude AI through the Model Context Protocol (MCP), enabling Claude to directly control QGIS — manage layers, edit features, run processing algorithms, render maps, and more.1001MIT
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants (Claude, Cursor, etc.) to QGIS 4.x via MCP, enabling natural language-driven GIS workflows through 37+ tools, including data loading, processing, and spatial analysis.GPL 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform geospatial analysis, spatial data processing, vector and raster operations, coordinate transformations, spatial statistics, mapping, and access to climate, satellite, and other geospatial data through MCP-compatible clients.MIT


