---
## 演示
https://github.com/user-attachments/assets/8a40565a-fcdd-47bf-ae67-bc870611c908
## 包
| 包名 | 描述 | npm |
|------|------|-----|
| [cesium-mcp-bridge](packages/cesium-mcp-bridge/) | 浏览器 SDK — 嵌入你的 CesiumJS 应用，通过 WebSocket 接收命令 | [](https://www.npmjs.com/package/cesium-mcp-bridge) |
| [cesium-mcp-runtime](packages/cesium-mcp-runtime/) | MCP 服务器 (stdio + HTTP) — 58 个工具（12 个工具集）+ 2 个资源，支持动态发现 | [](https://www.npmjs.com/package/cesium-mcp-runtime) |
| [cesium-mcp-dev](packages/cesium-mcp-dev/) | IDE MCP 服务器 — 为代码助手提供 CesiumJS API 辅助 | [](https://www.npmjs.com/package/cesium-mcp-dev) |
## 架构
```mermaid
flowchart LR
subgraph clients ["AI 客户端"]
A["Claude / Cursor\nVS Code"]
D["Dify / n8n\n远程 MCP"]
end
subgraph server ["cesium-mcp-runtime\n(Node.js)"]
R["MCP 服务器\n58 工具 · 12 工具集"]
end
subgraph browser ["浏览器"]
B["cesium-mcp-bridge"]
C["CesiumJS Viewer"]
end
A -- "stdio / MCP" --> R
D -- "Streamable HTTP" --> R
R -- "WebSocket\nJSON-RPC" --> B
B --> C
style clients fill:#1e293b,stroke:#528bff,color:#e2e8f0
style server fill:#1e293b,stroke:#155EEF,color:#e2e8f0
style browser fill:#1e293b,stroke:#12B76A,color:#e2e8f0
```
## 快速开始
### 1. 在你的 CesiumJS 应用中安装 bridge
```bash
npm install cesium-mcp-bridge
```
```js
import { CesiumBridge } from 'cesium-mcp-bridge';
const bridge = new CesiumBridge(viewer);
```
### 2. 启动 MCP 运行时
```bash
# stdio 模式（默认 — 用于 Claude Desktop、VS Code、Cursor）
npx cesium-mcp-runtime
# HTTP 模式（用于 Dify、远程/云端 MCP 客户端）
npx cesium-mcp-runtime --transport http --port 3000
```
### 3. 连接你的 AI 智能体
在 MCP 客户端配置中添加（如 Claude Desktop）：
```json
{
"mcpServers": {
"cesium": {
"command": "npx",
"args": ["-y", "cesium-mcp-runtime"]
}
}
}
```
然后对 AI 说：*"飞到埃菲尔铁塔，添加一个红色标记"*
## 58 个可用工具
工具按 **12 个工具集** 组织。默认启用 4 个核心工具集（约 31 个工具）。设置 `CESIUM_TOOLSETS=all` 启用全部，或由 AI 在运行时动态按需发现和激活。
> **国际化**: 工具描述默认英文，设置 `CESIUM_LOCALE=zh-CN` 切换中文。
| 工具集 | 工具 |
|--------|------|
| **view** (默认) | `flyTo`, `setView`, `getView`, `zoomToExtent`, `saveViewpoint`, `loadViewpoint`, `listViewpoints`, `exportScene` |
| **entity** (默认) | `addMarker`, `addLabel`, `addModel`, `addPolygon`, `addPolyline`, `updateEntity`, `removeEntity`, `batchAddEntities`, `queryEntities`, `getEntityProperties` |
| **layer** (默认) | `addGeoJsonLayer`, `listLayers`, `removeLayer`, `clearAll`, `setLayerVisibility`, `updateLayerStyle`, `getLayerSchema`, `setBasemap` |
| **interaction** (默认) | `screenshot`, `highlight`, `measure` |
| camera | `lookAtTransform`, `startOrbit`, `stopOrbit`, `setCameraOptions` |
| entity-ext | `addBillboard`, `addBox`, `addCorridor`, `addCylinder`, `addEllipse`, `addRectangle`, `addWall` |
| animation | `createAnimation`, `controlAnimation`, `removeAnimation`, `listAnimations`, `updateAnimationPath`, `trackEntity`, `controlClock`, `setGlobeLighting` |
| tiles | `load3dTiles`, `loadTerrain`, `loadImageryService`, `loadCzml`, `loadKml` |
| trajectory | `playTrajectory` |
| heatmap | `addHeatmap` |
| scene | `setSceneOptions`, `setPostProcess` |
| geolocation | `geocode` |
> **与 CesiumGS 官方 MCP 服务器的关系**：`camera`、`entity-ext` 和 `animation` 工具集原生融合了 [CesiumGS/cesium-mcp-server](https://github.com/CesiumGS/cesium-mcp-server)（Camera Server、Entity Server、Animation Server）的能力到本项目的统一 Bridge 架构中。一个 MCP 服务器即可获得全部官方功能加更多工具，无需运行多个进程。
## 示例
查看 [examples/minimal/](examples/minimal/) 获取完整工作示例。
## 开发
```bash
git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp
npm install
npm run build
```
## 版本策略
版本格式：`{Cesium主版本}.{Cesium次版本}.{MCP补丁号}`
| 版本段 | 含义 | 示例 |
|--------|------|------|
| `1.139` | 跟踪 CesiumJS 版本 — 基于 Cesium `~1.139.0` 构建与测试 | `1.139.8` → Cesium 1.139 |
| `.8` | MCP 补丁号 — 独立迭代，用于新增工具、缺陷修复、文档更新 | `1.139.7` → `1.139.8` |
当 CesiumJS 发布新次版本（如 1.140）时，我们将同步升级：`1.140.0`。
## 相关项目
- [mapbox-mcp](https://github.com/gaopengbin/mapbox-mcp) — AI 控制 Mapbox GL JS
- [openlayers-mcp](https://github.com/gaopengbin/openlayers-mcp) — AI 控制 OpenLayers
## Star 趋势
