快速开始

本指南介绍如何为桌面客户端和工作流平台配置 Node.js MCP runtime。如果你希望在兼容浏览器中直接暴露页面工具，而不启动 MCP 服务，请阅读 WebMCP 浏览器接入。

前置条件

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

安装

MCP 2026-07-28 预览版

cesium-mcp-runtime@1.143.4-next.0 已通过 npm next 标签发布。它从同一个 stdio/HTTP 入口同时支持现有 MCP 2025-11-25 客户端和新的 2026-07-28 协议。稳定版 latest 仍保持在 1.143.3。

npm install cesium-mcp-bridge@next
npx cesium-mcp-runtime@next

去掉 @next 即可回到稳定通道。

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)

2. 启动 MCP Runtime

stdio 模式（适用于 Claude Desktop、VS Code、Cursor）：

npx cesium-mcp-runtime

HTTP 模式（适用于 Dify、n8n 等 HTTP 平台）：

npx cesium-mcp-runtime --transport http --port 3211

运行后会启动一个 Node.js 进程，它会：

• 在所选传输方式（stdio 或 HTTP）上提供 MCP 工具
• 在 9100 端口开启 WebSocket 服务器（与浏览器 Bridge 通信）

要在任一模式下运行 MCP v2 预览版，请在包名后加 @next：

npx cesium-mcp-runtime@next
npx cesium-mcp-runtime@next --transport http --port 3211

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"]
    }
  }
}

在上述任一客户端配置中测试预览版时，将最后一个参数改为 "cesium-mcp-runtime@next"。

Dify / n8n（HTTP 传输模式）

首先以 HTTP 模式启动 Runtime：

npx cesium-mcp-runtime --transport http --port 3211

然后在 Dify 中添加 MCP 工具节点，配置如下：

{
  "cesium-mcp": {
    "transport": "streamable_http",
    "url": "http://localhost:3211/mcp",
    "timeout": 60
  }
}

Docker 部署的 Dify 需将 localhost 替换为 host.docker.internal。 完整指南：examples/dify-integration/

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
MCP_TRANSPORT	stdio	传输模式：stdio 或 http
MCP_HTTP_PORT	3211	HTTP 服务器端口（MCP_TRANSPORT=http 时生效）
HTTPS_PROXY	—	geocode 请求的 HTTP 代理地址（如 http://127.0.0.1:10808）
OSM_USER_AGENT	cesium-mcp-runtime/1.0	Nominatim geocode API 的 User-Agent
CESIUM_LOCALE	en	工具描述语言：en（英文，默认）或 zh-CN（中文）

代理配置

geocode 工具通过 HTTPS 调用 Nominatim API。如果需要代理（例如在国内网络），在 MCP 客户端配置中设置 HTTPS_PROXY：

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:10808"
      }
    }
  }
}

支持的变量：HTTPS_PROXY、HTTP_PROXY、ALL_PROXY。Runtime 使用 Node.js 内置的 undici.ProxyAgent，无需额外依赖。

最小示例

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

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

下一步

• 架构概览 — 了解共享执行层与独立适配层
• WebMCP 浏览器接入 — 无需 MCP 服务，直接暴露页面工具
• Bridge API — 全部 60 个浏览器命令
• Runtime API — MCP 工具和资源
• Dev API — IDE 编码辅助工具