Cesium Mcp Runtime

cesium-mcp-runtime

默认开启使用情况统计，并在启动时向 stderr 输出通知。设置 CESIUM_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1，或传入 --no-telemetry 即可停用。收集的字段与隐私。

English | 中文

通过 Model Context Protocol，让 AI Agent 能够实时控制 Cesium 地球仪的 MCP 服务。

发布渠道：latest 使用稳定版 MCP SDK v2，并通过同一个 stdio/HTTP 入口支持 MCP 2025-11-25 和 2026-07-28。 如果你只想体验「AI + Cesium」的效果， 推荐从 examples/browser-agent 开始——无需后端，三分钟即可运行。请参阅 我应该使用哪种模式？。

MCP Apps 地图面板

openCesiumMap 通过标准的 ui://cesium-mcp/map-v10.html MCP Apps 资源提供交互式 Cesium Viewer。地图占据主要区域，并通过 ui/message 使用宿主现有的原生聊天界面，不会重复显示输入框或历史记录。布局以及宿主主题／语言区域设置的变更不会影响 Viewer、选中项和会话。应用遵循宿主的语义样式变量和字体，支持中文和英文，并提供相机、图层和选中对象的上下文。本地预览控件可模拟宿主的实时设置并记录消息传递。还包含 OpenAI 全局／线程入口点和全屏提示。

构建后的 HTML、嵌入的 Worker 图以及 Bridge 包均包含在 dist 中。兼容的宿主必须支持 WebGL，以及在隔离且稳定的 UI 源下运行的 Blob 模块 Worker。嵌入式面板通过仅供应用使用的 MCP 工具交换命令，不访问本地 WebSocket。CESIUM_APP_DOMAIN 可用于指定专用 UI 源。外部浏览器 Viewer 仍使用现有的 WebSocket 传输方式。

如需进行真实的本地 MCP Apps 预览，请在已构建的仓库中运行 npm run app:preview -w packages/cesium-mcp-runtime，然后打开 http://127.0.0.1:19311/。请参阅[完整指南](https://gaopengbin.github.io/cesium-mcp/guide/mcp-apps)。针对特定客户端的 ChatGPT 安装是单独的验证步骤。

矢量瓦片

通过 CESIUM_TOOLSETS=view,entity,layer,interaction,tiles 或 enable_toolset 启用 tiles 工具集。使用 loadVectorTiles 加载 MVT /{z}/{x}/{y} URL 或矢量 3D Tiles，点击要素并读取 getSelectedTileFeature，然后使用 tileStyle.color 和 tileStyle.lineWidth 调用 updateLayerStyle，更新其托管图层的样式。读取 getLayerSchema.metadata.tileStyle，以验证已应用的表达式。

矢量渲染和贴地需要 CesiumJS 1.145。贴地线和多边形的拾取使用实验性的有界适配器。在 MCP Apps 面板中使用外部数据时，请通过 CESIUM_MAP_DATA_ORIGINS 配置精确的允许源。有关源格式、样式和限制，请参阅矢量瓦片指南。

架构

AI Agent <--MCP stdio--> cesium-mcp-runtime <--WebSocket--> Browser (cesium-mcp-bridge)
AI Agent <--MCP HTTP---> cesium-mcp-runtime <--WebSocket--> Browser (cesium-mcp-bridge)

运行时充当兼容 MCP 的 AI 客户端（Claude Desktop、VS Code Copilot、Cursor 等）与运行 CesiumJS 的浏览器之间的桥梁。它会将 MCP 工具调用转换为 WebSocket 命令，由 cesium-mcp-bridge 执行。

npm 包会在本地提供浏览器 Bridge 包。因此，内置 Viewer http://localhost:9100/ 不依赖 unpkg 回退；CesiumJS 本身仍从官方 Cesium CDN 加载。

对于普通 MCP 用户，只需安装一个包：运行 cesium-mcp-runtime 并使用内置 Viewer。只有在开发自定义 CesiumJS 页面时，才需要单独安装 cesium-mcp-bridge。

支持两种传输模式：

传输方式	使用场景	协议
stdio（默认）	本地 AI 客户端（Claude Desktop、VS Code、Cursor）	标准输入/输出
http	远程/云端 MCP 客户端（Dify、自定义后端）	流式 HTTP

安装与运行

# Stable channel (stdio mode, default)
npx -y cesium-mcp-runtime

# Or install globally
npm install -g cesium-mcp-runtime
cesium-mcp-runtime

然后打开 http://localhost:9100/ 使用内置 Viewer。此默认方式无需单独安装 Bridge。

流式 HTTP 模式

适用于 Dify 等远程/云端 MCP 客户端：

# Start in HTTP transport mode
npx -y cesium-mcp-runtime --transport http --port 3000

# MCP endpoint: POST http://localhost:3000/mcp

环境变量替代方式：

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx -y cesium-mcp-runtime

在 HTTP 模式下，默认启用全部 62 个 Cesium 命令工具（无需动态发现工具集）。

MCP 客户端配置

网络访问

默认情况下，运行时绑定到 127.0.0.1，包括其 HTTP 和 WebSocket 端口。 本地原生 MCP 客户端以及从 localhost 提供服务的页面仍可正常使用。 直接以 file:// 方式打开的页面必须改为通过本地 HTTP 服务提供。

变量	用途
CESIUM_HOST	绑定地址，默认为 127.0.0.1。非回环地址需要设置 CESIUM_AUTH_TOKEN。
CESIUM_AUTH_TOKEN	共享连接密钥。设置后，所有 API 和 WebSocket 连接都需要身份验证，包括本地客户端。
CESIUM_ALLOWED_HOSTS	以逗号分隔的精确主机名（不含端口），此外还允许回环地址和绑定地址。不支持通配符。
CESIUM_ALLOWED_ORIGINS	以逗号分隔的精确 HTTPS 页面来源。默认允许回环 HTTP/HTTPS 来源。不支持通配符。

要进行远程访问，请通过反向代理使用 HTTPS/WSS，并明确配置公共主机名和 Viewer 来源。例如，在服务器环境中设置 CESIUM_HOST=0.0.0.0、CESIUM_ALLOWED_HOSTS=maps.example.com、CESIUM_ALLOWED_ORIGINS=https://maps.example.com，以及生成的 CESIUM_AUTH_TOKEN。在代理中保留公共 Host 标头并启用 WebSocket 升级。

MCP HTTP 和 REST 客户端发送 Authorization: Bearer <token>。启用身份验证后，内置 Viewer 会提示输入连接令牌；令牌仅保存在页面中。自定义浏览器 Bridge 使用 WebSocket 子协议进行身份验证：

const encoded = btoa(String.fromCharCode(...new TextEncoder().encode(token)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
const ws = new WebSocket('wss://maps.example.com/?session=demo', [
  'cesium-mcp', `cesium-token.${encoded}`,
])

请勿将凭据放入查询字符串。反向代理不得记录 Authorization 或 Sec-WebSocket-Protocol 标头。Viewer HTML 和 Bridge 脚本是公共资源；受保护的 API 和 WebSocket 升级仍需令牌。次级本地 Runtime 实例必须使用相同的令牌，才能中继到现有实例。浏览器会话 ID 用于选择 Viewer，并非凭据。

Claude Desktop

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"],
      "env": {
        "CESIUM_WS_PORT": "9100",
        "DEFAULT_SESSION_ID": "default"
      }
    }
  }
}

VS Code（Copilot）

在 .vscode/mcp.json 中：

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

Cursor

在 .cursor/mcp.json 中：

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

MCP 工具（62 个命令工具 + 2 个发现元工具）

这些工具按 12 个工具集 组织。默认启用 4 个核心工具集（30 个工具）。可通过环境变量启用其他工具集，也可由 AI Agent 在运行时动态启用。共享标题、行为注释、本地化描述、默认值、输入验证、公布的输出架构和结构化结果均根据 cesium-mcp-contracts 中的规范 JSON 架构生成。工具调用也会保留文本 content，以兼容旧版客户端。

工具集概览

工具集	工具数	默认启用	描述
view	8	是	相机视图控制 + 视点书签 + 场景导出
entity	10	是	核心实体操作 + 批处理、查询和属性检查
layer	9	是	图层管理（GeoJSON、架构、样式、底图）
interaction	3	是	截图、高亮和测量
camera	4	—	高级相机控制（环绕、注视目标）
entity-ext	7	—	扩展实体类型（长方体、圆柱体、墙等）
animation	8	—	动画系统（航点、时钟、跟踪、照明）
tiles	7	—	3D Tiles、高斯泼溅、地形、影像服务、CZML 和 KML
trajectory	1	—	轨迹播放
heatmap	1	—	热力图可视化
scene	3	—	场景选项、后期处理和仅限运行时的 Ion 凭据
geolocation	1	—	地理编码——将地址/地点名称转换为坐标（Nominatim/OSM）

工具集配置

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

CESIUM_TOOLSETS 值	结果
（未设置）	默认 4 个工具集（30 个工具 + 2 个元工具）
view,entity,camera,animation	仅指定的工具集 + 2 个元工具
all	全部 62 个命令工具，不含元工具

动态发现（元工具）

在非 all 模式下，始终提供两个元工具，以便 AI 按需发现并启用其他功能：

工具	描述
list_toolsets	列出所有工具集组及其启用状态和工具名称
enable_toolset	动态启用工具集——新工具会立即可用

视图

工具	描述
flyTo	飞往指定坐标（经度、纬度、高度、航向、俯仰、翻滚、时长）
setView	立即设置相机位置
getView	获取当前相机状态
zoomToExtent	缩放至边界框（西、南、东、北）

实体

工具	描述
addMarker	在指定坐标添加标记
addLabel	在地图上添加文本标签
addModel	添加 3D 模型（glTF/GLB 或 Ion 资产）
addPolygon	添加多边形并设置样式
addPolyline	添加折线并设置样式
updateEntity	更新实体属性
removeEntity	按 ID 移除实体

图层

工具	描述
addGeoJsonLayer	添加 GeoJSON 并设置样式（分级设色、分类等）
listLayers	列出所有图层
removeLayer	按 ID 移除图层
setLayerVisibility	切换图层可见性
updateLayerStyle	更改图层颜色/不透明度/宽度
setBasemap	切换底图

相机 （工具集：camera）

工具	描述
lookAtTransform	以环绕式相机对准指定位置（航向/俯仰/距离）
startOrbit	开始围绕当前中心旋转相机
stopOrbit	停止环绕动画
setCameraOptions	配置相机控制器（启用/禁用旋转、缩放、倾斜）

扩展实体类型 (工具集：entity-ext)

工具	描述
addBillboard	在指定位置添加图像图标
addBox	添加具有指定尺寸和材质的 3D 方盒
addCorridor	添加廊道（具有宽度的路径）
addCylinder	添加圆柱体或圆锥体
addEllipse	添加椭圆形
addRectangle	根据地理边界添加矩形
addWall	沿指定位置添加墙体

动画 (工具集：animation)

工具	描述
createAnimation	使用航点创建基于时间的动画（使实体沿路径移动）
controlAnimation	播放或暂停当前动画
removeAnimation	移除动画实体
listAnimations	列出所有正在运行的动画
updateAnimationPath	更新动画路径的视觉属性
trackEntity	使用摄像机跟随实体
controlClock	配置 Cesium 时钟（时间范围、速度、动画状态）
setGlobeLighting	启用/禁用地球照明和大气效果

瓦片与数据 (工具集：tiles)

工具	描述
load3dTiles	从 URL 或 Ion 资产 ID 加载 3D Tiles
loadTerrain	设置地形提供程序
loadImageryService	添加影像服务（WMS/WMTS/XYZ/Ion）

交互 (工具集：interaction)

工具	描述
screenshot	将地图截取为 base64 PNG
highlight	高亮图层要素

其他

工具	工具集	描述
playTrajectory	trajectory	使实体沿坐标路径移动
addHeatmap	heatmap	根据点数据生成热力图

MCP 资源

URI	描述
cesium://scene/camera	当前摄像机位置、航向、俯仰角和翻滚角
cesium://scene/layers	所有已加载图层的列表，包含类型和可见性

环境变量

变量	默认值	描述
CESIUM_WS_PORT	9100	WebSocket 服务端口
DEFAULT_SESSION_ID	default	MCP 工具路由首选的浏览器会话
CESIUM_TOOLSETS	(未设置)	工具集激活方式：省略时使用默认值，all 表示启用所有工具集，也可使用逗号分隔的列表
CESIUM_LOCALE	en	工具描述语言：en（英语，默认）或 zh-CN（中文）
MCP_TRANSPORT	stdio	MCP 传输模式：stdio 或 http
MCP_HTTP_PORT	(自动)	Streamable HTTP 模式的 HTTP 端口（默认值：CESIUM_WS_PORT + 100）

浏览器端设置

浏览器页面需要通过 WebSocket 连接到运行时，并将命令转发给 cesium-mcp-bridge：

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

const bridge = new CesiumBridge(viewer)
const ws = new WebSocket('ws://localhost:9100?session=default')

ws.onmessage = async (event) => {
  const { id, method, params } = JSON.parse(event.data)
  try {
    const result = await bridge.execute({ action: method, params })
    ws.send(JSON.stringify({ id, result }))
  } catch (error) {
    ws.send(JSON.stringify({ id, error: { message: String(error) } }))
  }
}

会话路由

多个浏览器标签页可以使用不同的会话 ID 连接到同一个运行时：

Tab A: ws://localhost:9100?session=geoagent
Tab B: ws://localhost:9100?session=demo

通过 MCP URL 路由（推荐用于 Dify / 第三方集成）

在 MCP HTTP 端点 URL 中添加 ?session=xxx：

http://localhost:3216/mcp?session=geoagent

该连接发出的所有工具调用都会自动路由到匹配的浏览器，无需在提示词或工具参数中注入 sessionId。

路由优先级

1. 工具参数中的 sessionId（按单次调用显式覆盖）
2. MCP HTTP URL 中的 ?session=xxx（连接级别）
3. DEFAULT_SESSION_ID 环境变量
4. 第一个已连接的浏览器（回退）

显式路由采用失败关闭策略：如果工具参数或 MCP URL 指定的会话不存在或已断开连接，调用会返回错误，而不会在其他 Viewer 上运行。只有调用方未显式选择会话时，才会使用默认会话／第一个已连接的浏览器作为回退。待处理的响应也只会接受来自收到命令的浏览器的响应；如果该浏览器断开连接，则会立即拒绝响应。

资源句柄

运行时始终会注册 storeResource、listResources 和 deleteResource。将大型 GeoJSON 或 CZML 存储一次，然后把返回的 resourceId 传给 addGeoJsonLayer、addGeoJsonPrimitive、addLabel、addHeatmap 或 loadCzml。

资源按用于命令路由的同一浏览器 sessionId 隔离。资源默认在 30 分钟后过期，且只有在调用工具解析句柄后才会转发到浏览器。现有的内联 data 和远程 url 输入仍保持兼容。

请参阅资源句柄指南。

HTTP 推送 API

运行时还会为非 MCP 集成（例如 FastAPI 后端）提供一个 HTTP 端点：

curl -X POST http://localhost:9100/push \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "default", "command": {"action": "flyTo", "params": {"longitude": 116.39, "latitude": 39.91}}}'

兼容性

通道	运行时	桥接	MCP 协议	Cesium
latest	当前稳定版	对应的稳定版	2025-11-25 + 2026-07-28	~1.145.0

稳定版使用 @modelcontextprotocol/server 和 @modelcontextprotocol/node 2.0.0 包，通过同一个 stdio/HTTP 入口支持这两代协议。

仓库单独固定了官方一致性测试运行器，并使用以下命令验证 2026-07-28 的 server-stateless 场景：

npm run test:conformance:mcp

仅此命令会启用仅用于一致性测试的诊断工具。正常启动 stdio、HTTP 或浏览器演示运行时时不会注册这些工具。

许可证

MIT