让 AI 用自然语言操控三维地球 -- Cesium MCP 开源实践

一句"飞到埃菲尔铁塔，加个红色标记"，Claude/Copilot/Cursor 就能帮你在 CesiumJS 里完成操作。这是怎么做到的？

演示效果

先看效果，了解 cesium-mcp 能做什么：

演示中通过 AI 对话完成了相机飞行、添加标记、样式修改等操作。

背景：当 GIS 遇上 AI Agent

CesiumJS 是 WebGL 三维地球可视化的事实标准。但凡涉及地理信息系统（GIS）的 Web 项目------智慧城市、数字孪生、无人机航线规划------几乎绑定 CesiumJS。

问题是：Cesium API 体量庞大，光 Viewer 就有几十个配置项，Entity 系统更是嵌套层层。新人写个"在地图上加个点"都要翻半天文档。

2024 年底 Anthropic 推出了 MCP（Model Context Protocol），让 AI 智能体能以标准化方式调用外部工具。我们顺着这条路做了一件事：

把 CesiumJS 的能力通过 MCP 协议暴露出来，让任何 AI 智能体都能用自然语言操控三维地球。

这就是 cesium-mcp。

它能做什么

整体架构

graph LR subgraph AI["AI 智能体"] A1["Claude Desktop"] A2["VS Code Copilot"] A3["Cursor"] end subgraph MCP_Server["cesium-mcp-runtime
(Node.js MCP Server)"] R1["MCP stdio 接口"] R2["WebSocket Server"] end subgraph Browser["浏览器"] B1["cesium-mcp-bridge
(SDK)"] C1["CesiumJS Viewer
三维地球"] end A1 -->|"MCP 协议
(stdio)"| R1 A2 -->|"MCP 协议
(stdio)"| R1 A3 -->|"MCP 协议
(stdio)"| R1 R1 <--> R2 R2 <-->|"WebSocket
JSON-RPC"| B1 B1 -->|"命令执行"| C1 style AI fill:#e8f4f8,stroke:#2196F3,stroke-width:2px style MCP_Server fill:#fff3e0,stroke:#FF9800,stroke-width:2px style Browser fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px

简单说就是三层：

cesium-mcp-bridge（浏览器 SDK）：嵌入你的 CesiumJS 应用，通过 WebSocket 接收命令并执行
cesium-mcp-runtime（MCP Server）：连接 AI 智能体和浏览器，暴露 19 个标准化工具
cesium-mcp-dev（开发辅助 MCP Server）：在 IDE 里让 AI 助手更懂 Cesium API

19 个工具，覆盖 GIS 核心场景

类别	工具	说明
相机	`flyTo` `setView` `getView` `zoomToExtent`	飞行定位、视角切换
图层	`addGeoJsonLayer` `addHeatmap` `addMarker` `addLabel`	数据叠加、热力图
图层管理	`removeLayer` `setLayerVisibility` `listLayers` `updateLayerStyle`	增删改查
三维数据	`load3dTiles` `loadTerrain` `loadImageryService`	3D Tiles、地形、影像服务
底图	`setBasemap`	天地图、ArcGIS、OSM 一键切换
交互	`highlight` `screenshot`	要素高亮、截图
动画	`playTrajectory`	沿路径播放轨迹动画

你对 AI 说"加载这个 GeoJSON，用渐变色渲染人口密度"，它会自动调用 addGeoJsonLayer 并传入样式参数。

三分钟跑起来

第一步：浏览器嵌入 bridge

bash 复制代码

npm install cesium-mcp-bridge

typescript 复制代码

import { CesiumMcpBridge } from 'cesium-mcp-bridge';

// viewer 是你已有的 Cesium.Viewer 实例
const bridge = new CesiumMcpBridge(viewer, { port: 9100 });
bridge.connect();

第二步：启动 MCP 运行时

bash 复制代码

npx cesium-mcp-runtime

第三步：接入 AI 智能体

以 Claude Desktop 为例，在配置文件中添加：

json 复制代码

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

VS Code Copilot 用户在 .vscode/mcp.json 中配置：

json 复制代码

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

然后直接用自然语言下指令：

"飞到北京天安门，高度 1000 米"
"加载这个 3D Tiles 模型"
"画一条从上海到纽约的折线"
"截张图发我"

开发时也有 AI 加持

除了运行时操控，我们还做了 cesium-mcp-dev------专为 IDE AI 助手设计的 MCP 服务器：

graph LR subgraph IDE["IDE 环境"] D1["GitHub Copilot"] D2["Cursor AI"] D3["Claude Code"] end subgraph DevServer["cesium-mcp-dev
(MCP Server)"] T1["cesium_api_lookup
API 文档查询"] T2["cesium_code_gen
代码生成"] T3["cesium_entity_builder
Entity 构建器"] end subgraph Output["输出"] O1["API 签名 & 示例"] O2["TypeScript 代码片段"] O3["Entity 配置 JSON"] end D1 -->|"MCP stdio"| DevServer D2 -->|"MCP stdio"| DevServer D3 -->|"MCP stdio"| DevServer T1 --> O1 T2 --> O2 T3 --> O3 style IDE fill:#f3e5f5,stroke:#9C27B0,stroke-width:2px style DevServer fill:#fff3e0,stroke:#FF9800,stroke-width:2px style Output fill:#e8f5e9,stroke:#4CAF50,stroke-width:2px

提供 3 个工具：

工具	功能
`cesium_api_lookup`	按类名/方法查 Cesium API 文档，覆盖 Viewer、Entity、Camera 等 12 个核心类
`cesium_code_gen`	自然语言生 Cesium 代码，内置 11 个常见场景模板
`cesium_entity_builder`	交互式构建 Entity 配置，支持 8 种类型（point/polygon/model 等）

配置方式和 runtime 完全一致：

json 复制代码

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

这意味着你在 VS Code 里写 Cesium 代码时，Copilot 可以直接查 API、生成代码片段、构建 Entity 配置------再也不用频繁切到文档网站。

一次操控的完整流程

以"飞到北京天安门，加个红色标记"为例，看看数据是怎么流转的：

sequenceDiagram participant User as 用户 participant AI as AI 智能体 participant RT as cesium-mcp-runtime participant BR as cesium-mcp-bridge participant CS as CesiumJS User->>AI: "飞到北京天安门，加个红色标记" AI->>AI: 理解意图，拆解为两步 rect rgb(232, 244, 248) Note over AI,CS: 第一步：飞行定位 AI->>RT: MCP tool_call: flyTo({lon:116.39, lat:39.91, h:1000}) RT->>BR: WebSocket JSON-RPC BR->>CS: viewer.camera.flyTo(...) CS-->>BR: 飞行完成 BR-->>RT: result: success RT-->>AI: tool_result: "已飞行到目标位置" end rect rgb(232, 245, 233) Note over AI,CS: 第二步：添加标记 AI->>RT: MCP tool_call: addMarker({lon:116.39, lat:39.91, color:"red"}) RT->>BR: WebSocket JSON-RPC BR->>CS: viewer.entities.add(...) CS-->>BR: entity created BR-->>RT: result: {id: "marker-1"} RT-->>AI: tool_result: "已添加红色标记" end AI-->>User: "已飞到天安门并添加了红色标记"

AI 自动将自然语言拆解为多个工具调用，每个工具走完 MCP -> WebSocket -> CesiumJS 的完整链路，结果逐级回传。用户只需要说一句话。

技术实现要点

Bridge：命令注册与执行

cesium-mcp-bridge 的核心是一个命令注册表。每个 MCP 工具对应一个命令处理器，通过 CesiumBridge.execute() 分发：

typescript 复制代码

const bridge = new CesiumBridge(viewer);
// 收到 WebSocket 消息后
const result = await bridge.execute({
  action: 'flyTo',
  params: { longitude: 116.4, latitude: 39.9, height: 1000 }
});

Bridge 不关心命令从哪来------WebSocket、HTTP、甚至手动调用都行。这种解耦使得 Bridge SDK 可以独立于 MCP 使用。

Runtime：双向通信

Runtime 同时充当 MCP stdio 服务器和 WebSocket 服务器。AI 智能体通过 MCP 协议发送工具调用，Runtime 把它翻译成 JSON-RPC 命令通过 WebSocket 推给浏览器，等待执行结果后回传给 AI。

支持多会话（session），同一个 Runtime 可以连接多个浏览器页面。

版本策略

主版本号.次版本号跟踪 CesiumJS（1.139.x 对应 Cesium ~1.139.0），补丁版本独立迭代 MCP 功能。这样用户一看版本号就知道兼容哪个 Cesium。

已上架平台

平台	状态
npm Registry	`cesium-mcp-bridge` / `cesium-mcp-runtime` / `cesium-mcp-dev` v1.139.2
MCP Official Registry	`io.github.gaopengbin/cesium-mcp-runtime` / `cesium-mcp-dev`
Smithery	runtime（19 tools）/ dev（3 tools）
awesome-mcp-servers	PR 已提交

适用场景

快速原型：用自然语言几分钟搭出 GIS 可视化 demo
非开发人员：分析师、项目经理可以直接对 AI 说需求，AI 在 Cesium 上渲染结果
教学演示：课堂上让学生用自然语言探索地理数据
自动化流水线：CI/CD 中自动截图、自动验证地图渲染
智慧城市/数字孪生：AI Agent 作为交互层，终端用户通过对话操控三维场景

参与贡献

项目完全开源（MIT），欢迎参与：

bash 复制代码

git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp
npm install
npm run build
npm test

GitHub: github.com/gaopengbin/... 官方文档: gaopengbin.github.io/cesium-mcp

如果你也在做 GIS + AI 的事情，欢迎交流。有问题直接在 GitHub Issues 提，我们会及时回复。