快速开始

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

前置条件

• Node.js 20 或更高版本
• 一个 兼容 MCP 的 AI 客户端（Claude Desktop、VS Code Copilot、Cursor 等）
• 独立的 CesiumJS 应用不是必需项；Runtime 已提供可直接使用的 Viewer

一包快速开始

MCP SDK v2 已稳定

npm latest 稳定版通过同一个 stdio/HTTP 入口同时支持现有 MCP 2025-11-25 客户端和新的 2026-07-28 协议。

npx -y cesium-mcp-runtime

普通 MCP 用户只需要 cesium-mcp-runtime 一个包。它已经包含 MCP Server、WebSocket 会话路由、浏览器 Bridge bundle，以及位于 http://localhost:9100/ 的内置 Cesium Viewer。

手动启动

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

npx -y cesium-mcp-runtime

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

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

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

• 在所选传输方式（stdio 或 HTTP）上提供 MCP 工具
• 在 9100 端口开启 Viewer 会话所需的 WebSocket 服务器
• 在 http://localhost:9100/ 提供内置 Viewer
• 通过 /bridge.js 提供包内自带的浏览器 Bridge

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

Dify / n8n（HTTP 传输模式）

首先以 HTTP 模式启动 Runtime：

npx -y 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/

试一试

在浏览器中打开 http://localhost:9100/，然后对 AI 智能体说：

"飞到埃菲尔铁塔"

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

自定义 CesiumJS 应用（可选）

只有当你希望 MCP 命令控制自己应用中的 Viewer，而不是内置 Viewer 时，才需要单独安装 cesium-mcp-bridge：

npm install cesium-mcp-bridge

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

const viewer = new Cesium.Viewer('cesiumContainer')
const bridge = new CesiumBridge(viewer)

自定义页面还需要把 Bridge 连接到 Runtime WebSocket。完整实现请参考最小自定义页面示例。这是应用开发路径，不是普通 MCP 用户的安装前提。

仅 IDE 模式 (cesium-mcp-dev)

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

npx -y 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 编码辅助工具