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

掘金前端

作者 laogao

2026年3月15日 16:53

让 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<br/>(Node.js MCP Server)"]
        R1["MCP stdio 接口"]
        R2["WebSocket Server"]
    end

    subgraph Browser["浏览器"]
        B1["cesium-mcp-bridge<br/>(SDK)"]
        C1["CesiumJS Viewer<br/>三维地球"]
    end

    A1 -->|"MCP 协议<br/>(stdio)"| R1
    A2 -->|"MCP 协议<br/>(stdio)"| R1
    A3 -->|"MCP 协议<br/>(stdio)"| R1
    R1 <--> R2
    R2 <-->|"WebSocket<br/>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

npm install cesium-mcp-bridge

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

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

第二步：启动 MCP 运行时

npx cesium-mcp-runtime

第三步：接入 AI 智能体

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

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

VS Code Copilot 用户在 .vscode/mcp.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<br/>(MCP Server)"]
        T1["cesium_api_lookup<br/>API 文档查询"]
        T2["cesium_code_gen<br/>代码生成"]
        T3["cesium_entity_builder<br/>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 完全一致：

{
  "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() 分发：

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），欢迎参与：

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 提，我们会及时回复。

普通视图

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

演示效果

背景：当 GIS 遇上 AI Agent

它能做什么

整体架构

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

三分钟跑起来

第一步：浏览器嵌入 bridge

第二步：启动 MCP 运行时

第三步：接入 AI 智能体

开发时也有 AI 加持

一次操控的完整流程

技术实现要点

Bridge：命令注册与执行

Runtime：双向通信

版本策略

已上架平台

适用场景

参与贡献