快速开始

前置条件

• Node.js 20 或更高版本
• 一个 CesiumJS 应用（或使用我们提供的最小示例）
• 一个 兼容 MCP 的 AI 客户端（Claude Desktop、VS Code Copilot、Cursor 等）

安装

1. 在 CesiumJS 应用中添加 Bridge

npm install cesium-mcp-bridge

创建 Cesium Viewer 后初始化 Bridge：

import { CesiumBridge } from 'cesium-mcp-bridge'

const viewer = new Cesium.Viewer('cesiumContainer')
const bridge = new CesiumBridge(viewer, {
  wsUrl: 'ws://localhost:9100',
  sessionId: 'default',
})

2. 启动 MCP Runtime

npx cesium-mcp-runtime

这会启动一个 Node.js 进程：

• 通过 stdio 监听 MCP 工具调用（来自 AI 智能体）
• 在 9100 端口开启 WebSocket 服务器（供浏览器 Bridge 连接）

3. 配置 AI 智能体

Claude Desktop

编辑 claude_desktop_config.json：

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

VS Code (GitHub Copilot)

创建 .vscode/mcp.json：

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

Cursor

创建 .cursor/mcp.json：

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

4. 试一试

在浏览器中打开你的 CesiumJS 应用，然后对 AI 智能体说：

"飞到埃菲尔铁塔"

智能体会调用 flyTo 工具，指令通过 Runtime 路由到 Bridge，你的地球将自动飞行到巴黎。

仅 IDE 模式 (cesium-mcp-dev)

如果你只需要 AI 辅助编写 CesiumJS 代码（不需要实时地球），可以安装 dev 服务器：

npx cesium-mcp-dev

它提供：

• API 文档查询 — 查询 Cesium 类、方法、属性
• 代码片段生成 — 获取常见模式的可运行代码
• Entity 模板构建器 — 根据描述生成 Entity 配置

配置方式与 Runtime 相同，将 cesium-mcp-runtime 替换为 cesium-mcp-dev 即可。

环境变量

变量	默认值	描述
CESIUM_WS_PORT	9100	WebSocket 服务器端口
DEFAULT_SESSION_ID	default	多标签页路由的会话 ID

最小示例

仓库中包含完整的单文件示例：

git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp/examples/minimal
# 在浏览器中打开 index.html

下一步

• 架构概览 — 了解三包架构设计
• Bridge API — 全部 19 个命令
• Runtime API — MCP 工具和资源
• Dev API — IDE 编码辅助工具