Cesium MCP

简体中文

English

简体中文

English

Appearance

cesium-mcp-runtime ​

MCP 服务器（stdio）— 58 个工具（12 个工具集）+ 2 个资源，支持动态发现。

npm

安装与运行 ​

bash
npx cesium-mcp-runtime

或全局安装：

bash
npm install -g cesium-mcp-runtime
cesium-mcp-runtime

MCP 客户端配置 ​

Claude Desktop ​

claude_desktop_config.json：

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

VS Code (GitHub Copilot) ​

.vscode/mcp.json：

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

Cursor ​

.cursor/mcp.json：

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

MCP 工具（58 + 2 元工具） ​

工具按 12 个工具集 组织。默认启用 4 个核心工具集（约 31 个工具）。设置 CESIUM_TOOLSETS=all 启用全部，或由 AI 在运行时动态发现和激活。

工具集 ​

工具集工具数默认启用描述
view8是相机视角控制 + 视点书签 + 场景导出
entity10是核心实体操作 + 批量、查询与属性查看
layer8是图层管理（GeoJSON、Schema、样式、底图）
interaction3是截图、高亮与测量
camera4—高级相机控制（环绕、注视）
entity-ext7—扩展实体类型（盒体、柱体、墙等）
animation8—动画系统（路径点、时钟、追踪、光照）
tiles5—3D Tiles、地形、影像服务、CZML 与 KML
trajectory1—轨迹回放
heatmap1—热力图可视化
scene2—场景选项与后处理效果
geolocation1—地理编码 — 将地址/地名转换为坐标（Nominatim/OSM）

动态发现 ​

非 all 模式下，始终注册两个元工具：

工具描述
list_toolsets列出所有工具集及其启用状态
enable_toolset在运行时动态启用一个工具集

视图 ​

flyTo ​

相机飞行到指定位置（带动画过渡）。

参数类型必填默认值说明
longitudenumber✅—经度（-180 ~ 180）
latitudenumber✅—纬度（-90 ~ 90）
heightnumber—50000相机高度（米）
headingnumber—0航向角（度），0 = 正北
pitchnumber—-45俯仰角（度），-90 = 正下方
durationnumber—2飞行动画时长（秒）

setView ​

瞬间切换到指定视角（无动画）。

参数类型必填默认值说明
longitudenumber✅—经度（-180 ~ 180）
latitudenumber✅—纬度（-90 ~ 90）
heightnumber—50000高度（米）
headingnumber—0航向角（度）
pitchnumber—-90俯仰角（度）
rollnumber—0翻滚角（度）

getView ​

获取当前相机状态。无参数。

返回： { longitude, latitude, height, heading, pitch, roll }

zoomToExtent ​

缩放适配到地理包围盒。

参数类型必填默认值说明
westnumber✅—西边界经度
southnumber✅—南边界纬度
eastnumber✅—东边界经度
northnumber✅—北边界纬度
durationnumber—2动画时长（秒）

saveViewpoint ​

将当前相机状态保存为命名视点书签。

参数类型必填默认值说明
namestring✅—视点书签名称

返回值： 保存的 ViewState 对象。

loadViewpoint ​

恢复先前保存的视点书签。

参数类型必填默认值说明
namestring✅—视点书签名称
durationnumber—0飞行时长（秒，0 = 立即跳转）

返回值： 恢复的 ViewState，未找到则报错。

listViewpoints ​

列出所有已保存的视点书签。无参数。

返回值： [{ name, state: ViewState }]

exportScene ​

将当前场景中的所有实体和图层导出为结构化 JSON 快照。

无参数。

返回值： { entities: [...], layers: [...], camera: ViewState }

实体 ​

addMarker ​

添加点标记，可附加标注。返回 entityId。

参数类型必填默认值说明
longitudenumber✅—经度（-180 ~ 180）
latitudenumber✅—纬度（-90 ~ 90）
labelstring——标注文本
colorstring—"#3B82F6"CSS 颜色
sizenumber—12点大小（像素）
idstring—自动自定义图层 ID

addLabel ​

为 GeoJSON 要素添加文本标注。

参数类型必填默认值说明
dataobject✅—GeoJSON FeatureCollection
fieldstring✅—标注字段名
styleobject——标注样式（font, fillColor, outlineColor, scale）

addModel ​

在指定位置放置 3D 模型（glTF/GLB）。返回 entityId。

参数类型必填默认值说明
longitudenumber✅—经度
latitudenumber✅—纬度
heightnumber—0高度（米）
urlstring✅—glTF/GLB 模型 URL
scalenumber—1缩放比例
headingnumber—0航向角（度）
pitchnumber—0俯仰角（度）
rollnumber—0翻滚角（度）
labelstring——模型标注

addPolygon ​

添加多边形区域。返回 entityId。

参数类型必填默认值说明
coordinatesnumber[][]✅—外环坐标 [[lon, lat, height?], ...]
colorstring—"#3B82F6"填充颜色
outlineColorstring—"#FFFFFF"描边颜色
opacitynumber—0.6透明度（0–1）
extrudedHeightnumber——拉伸高度（米）
clampToGroundboolean—true是否贴地
labelstring——标注文本

addPolyline ​

添加折线。返回 entityId。

参数类型必填默认值说明
coordinatesnumber[][]✅—坐标 [[lon, lat, height?], ...]
colorstring—"#3B82F6"线条颜色
widthnumber—3线宽（像素）
clampToGroundboolean—true是否贴地
labelstring——标注文本

updateEntity ​

更新已有实体属性。

参数类型必填默认值说明
entityIdstring✅—要更新的实体 ID
positionobject——新位置 { longitude, latitude, height? }
labelstring——新标注
colorstring——新颜色
scalenumber——新缩放
showboolean——可见性

removeEntity ​

按 ID 移除单个实体。

参数类型必填默认值说明
entityIdstring✅—要移除的实体 ID

batchAddEntities ​

在一次调用中添加多个不同类型的实体。

参数类型必填默认值说明
entitiesobject[]✅—实体定义数组

每个实体对象必须包含 type 字段（"marker", "polyline", "polygon", "model", "label", "billboard", "box", "cylinder", "ellipse", "rectangle", "wall", "corridor"）以及该实体类型对应的参数。

返回值： { entityIds: string[], errors: string[] }

queryEntities ​

搜索和筛选场景中的实体。

参数类型必填默认值说明
namestring——按名称筛选（模糊匹配，不区分大小写）
typestring——按类型筛选（"point", "billboard", "label", "model", "polyline", "polygon"）
bboxnumber[]——包围盒筛选 [west, south, east, north]

返回值： [{ entityId, name?, type, position? }]

getEntityProperties ​

获取指定实体的所有属性。

参数类型必填默认值说明
entityIdstring✅—实体 ID

返回值： { entityId, name, type, position?, properties }

图层 ​

addGeoJsonLayer ​

加载 GeoJSON 数据作为图层。支持内联数据和 URL 加载两种方式。

参数类型必填默认值说明
dataobject——GeoJSON FeatureCollection（内联数据）
urlstring——GeoJSON 文件 URL（浏览器端加载）
idstring—自动图层 ID
namestring——显示名称
styleobject——样式配置（color, opacity, pointSize, strokeWidth, randomColor, gradient, choropleth, category）

data 和 url 至少提供其一。

listLayers ​

列出当前所有图层。无参数。

返回： [{ id, name, type, visible, color }]

removeLayer ​

按 ID 移除图层。

参数类型必填默认值说明
idstring✅—图层 ID

clearAll ​

移除所有图层、实体和数据源。无参数。

setLayerVisibility ​

切换图层可见性。

参数类型必填默认值说明
idstring✅—图层 ID
visibleboolean✅—是否可见

updateLayerStyle ​

修改图层样式。

参数类型必填默认值说明
layerIdstring✅—图层 ID
labelStyleobject——标注样式（font, fillColor, outlineColor, outlineWidth, scale）
layerStyleobject——图层样式（color, opacity, strokeWidth, pointSize）
tileStyleobject——3D Tiles 样式（Cesium3DTileStyle 表达式：color, show, pointSize, meta）

getLayerSchema ​

获取图层属性字段结构（GeoJSON DataSource 或 3D Tiles 批量表）。

参数类型必填默认值说明
layerIdstring✅—图层 ID

返回值： { layerId, layerName, entityCount, fields: [{ name, type, sample? }] }

setBasemap ​

切换底图影像。

参数类型必填默认值说明
basemapstring✅—"dark" | "satellite" | "standard"

相机 ​

lookAtTransform ​

环绕式相机注视目标位置。

参数类型必填默认值说明
longitudenumber✅—目标经度
latitudenumber✅—目标纬度
heightnumber—0目标高度（米）
headingnumber—0相机航向角（度）
pitchnumber—-45相机俯仰角（度）
rangenumber—1000距目标距离（米）

startOrbit ​

开始相机环绕旋转。

参数类型必填默认值说明
speednumber—0.005旋转速度（弧度/帧）
clockwiseboolean—true旋转方向

stopOrbit ​

停止环绕动画。无参数。

setCameraOptions ​

配置相机控制器选项。

参数类型必填默认值说明
enableRotateboolean——启用旋转
enableTranslateboolean——启用平移
enableZoomboolean——启用缩放
enableTiltboolean——启用倾斜
enableLookboolean——启用环视
minimumZoomDistancenumber——最小缩放距离（米）
maximumZoomDistancenumber——最大缩放距离（米）
enableInputsboolean——启用/禁用所有输入

扩展实体类型 ​

addBillboard ​

在指定位置添加图片图标。

参数类型必填默认值说明
longitudenumber✅—经度
latitudenumber✅—纬度
heightnumber—0高度（米）
imagestring✅—图片 URL
namestring——名称
scalenumber—1.0缩放
colorColorInput——着色
pixelOffset{x, y}——像素偏移
heightReferencestring——"NONE" | "CLAMP_TO_GROUND" | "RELATIVE_TO_GROUND"

addBox ​

添加 3D 盒体。

参数类型必填默认值说明
longitudenumber✅—经度
latitudenumber✅—纬度
heightnumber—0高度（米）
dimensionsobject✅—尺寸 { width, length, height }（米）
namestring——名称
materialMaterialInput——材质
outlineboolean—true显示轮廓
outlineColorColorInput——轮廓颜色
fillboolean—true显示填充
orientationobject——方向 { heading, pitch, roll }（度）

addCorridor ​

添加走廊（带宽度的路径）。

参数类型必填默认值说明
positionsPositionDegrees[]✅—位置数组 [{ longitude, latitude, height? }]
widthnumber✅—宽度（米）
namestring——名称
materialMaterialInput——材质
cornerTypestring——"ROUNDED" | "MITERED" | "BEVELED"
heightnumber——离地高度
extrudedHeightnumber——拉伸高度

addCylinder ​

添加圆柱体或圆锥体。

参数类型必填默认值说明
longitudenumber✅—经度
latitudenumber✅—纬度
heightnumber—0高度（米）
lengthnumber✅—柱体高度（米）
topRadiusnumber✅—顶部半径（米）
bottomRadiusnumber✅—底部半径（米）
namestring——名称
materialMaterialInput——材质
outlineboolean—true显示轮廓
slicesnumber—128切片数

addEllipse ​

添加椭圆。

参数类型必填默认值说明
longitudenumber✅—中心经度
latitudenumber✅—中心纬度
heightnumber—0高度（米）
semiMajorAxisnumber✅—长半轴（米）
semiMinorAxisnumber✅—短半轴（米）
namestring——名称
materialMaterialInput——材质
extrudedHeightnumber——拉伸高度
rotationnumber——旋转角（弧度）
outlineboolean——显示轮廓

addRectangle ​

添加矩形。

参数类型必填默认值说明
westnumber✅—西边界经度
southnumber✅—南边界纬度
eastnumber✅—东边界经度
northnumber✅—北边界纬度
namestring——名称
materialMaterialInput——材质
heightnumber——高度
extrudedHeightnumber——拉伸高度
outlineboolean——显示轮廓

addWall ​

沿路径添加墙体。

参数类型必填默认值说明
positionsPositionDegrees[]✅—位置数组 [{ longitude, latitude, height? }]
namestring——名称
minimumHeightsnumber[]——各位置最小高度
maximumHeightsnumber[]——各位置最大高度
materialMaterialInput——材质
outlineboolean——显示轮廓

动画 ​

createAnimation ​

创建基于时间的路径动画（实体沿路径移动）。

参数类型必填默认值说明
waypointsobject[]✅—[{ longitude, latitude, height?, time }]，time 为 ISO 8601
namestring——动画名称
modelUristring——glTF URL 或预设：cesium_man, cesium_air, ground_vehicle, cesium_drone
showPathboolean—true显示轨迹线
pathWidthnumber—2轨迹宽度（像素）
pathColorstring—"#00FF00"轨迹颜色
pathLeadTimenumber—0前导时间（秒）
pathTrailTimenumber—1e10尾迹时间（秒）
multipliernumber—1时钟倍速
shouldAnimateboolean—true自动开始

controlAnimation ​

播放或暂停动画。

参数类型必填默认值说明
actionstring✅—"play" | "pause"

removeAnimation ​

删除动画实体。

参数类型必填默认值说明
entityIdstring✅—要删除的动画实体 ID

listAnimations ​

列出所有活跃动画。无参数。

返回： [{ entityId, name?, startTime, stopTime, exists }]

updateAnimationPath ​

更新动画路径的可视属性。

参数类型必填默认值说明
entityIdstring✅—动画实体 ID
widthnumber——路径宽度（像素）
colorstring——路径颜色
leadTimenumber——前导时间（秒）
trailTimenumber——尾迹时间（秒）
showboolean——显示/隐藏路径

trackEntity ​

相机追踪实体，或停止追踪。

参数类型必填默认值说明
entityIdstring——要追踪的实体 ID（省略则停止追踪）
headingnumber——相机航向角（度）
pitchnumber—-30相机俯仰角（度）
rangenumber—500相机距离（米）

controlClock ​

配置 Cesium 时钟。

参数类型必填默认值说明
actionstring✅—"configure" | "setTime" | "setMultiplier"
startTimestring——ISO 8601 开始时间
stopTimestring——ISO 8601 结束时间
currentTimestring——ISO 8601 当前时间
timestring——跳转时间（用于 setTime）
multipliernumber——时钟倍速
shouldAnimateboolean——是否播放
clockRangestring——"UNBOUNDED" | "CLAMPED" | "LOOP_STOP"

setGlobeLighting ​

启用/禁用地球光照和大气效果。

参数类型必填默认值说明
enableLightingboolean——启用地球光照
dynamicAtmosphereLightingboolean——动态大气光照
dynamicAtmosphereLightingFromSunboolean——使用太阳位置计算大气光照

3D 数据 ​

load3dTiles ​

从 URL 或 Cesium Ion 资产 ID 加载 3D Tileset（建筑白膜、城市模型等）。

参数类型必填默认值说明
urlstring——tileset.json URL
ionAssetIdnumber——Cesium Ion 资产 ID
idstring—自动图层 ID
namestring——显示名称
maximumScreenSpaceErrornumber—16最大屏幕空间误差（值越小越精细）
heightOffsetnumber——高度偏移（米）

url 和 ionAssetId 至少提供其一。

loadTerrain ​

设置地形提供者。

参数类型必填默认值说明
providerstring✅—"flat" | "arcgis" | "cesiumion"
urlstring——自定义地形服务 URL
cesiumIonAssetIdnumber——Cesium Ion 资产 ID

loadImageryService ​

从 URL 或 Cesium Ion 资产 ID 添加影像图层。

参数类型必填默认值说明
urlstring——影像服务 URL
serviceTypestring——"wms" | "wmts" | "xyz" | "arcgis_mapserver" | "ion"
ionAssetIdnumber——Cesium Ion 资产 ID
idstring—自动图层 ID
namestring——显示名称
layerNamestring——WMS/WMTS 图层名
opacitynumber—1.0透明度（0–1）

url + serviceType 和 ionAssetId 至少提供其一。

loadCzml ​

加载 CZML 时间动态数据源（内联数据数组或远程 URL）。

参数类型必填默认值说明
dataunknown[]——CZML 数据包数组（内联）
urlstring——CZML 文件 URL
idstring—自动图层 ID
namestring——显示名称
sourceUristring——相对引用的基础 URI
clampToGroundboolean—false是否贴地

data 和 url 至少提供其一。

loadKml ​

加载 KML/KMZ 数据源（内联字符串或远程 URL）。

参数类型必填默认值说明
datastring——KML 文档字符串（内联）
urlstring——KML/KMZ 文件 URL
idstring—自动图层 ID
namestring——显示名称
clampToGroundboolean—false是否贴地

data 和 url 至少提供其一。

交互 ​

screenshot ​

截取当前地球视图。无参数。

返回： Base64 PNG 图片（MCP image 内容类型）。

highlight ​

高亮指定图层的要素。

参数类型必填默认值说明
layerIdstring✅—图层 ID
featureIndexnumber——要素索引（省略则高亮全部）
colorstring—"#FFFF00"高亮颜色

measure ​

测量地球表面上两点间的距离或多点围成的面积。

参数类型必填默认值说明
typestring✅—"distance" | "area"
coordinatesnumber[][]✅—坐标点 [[lon, lat], ...]（距离需 2 个点，面积需 3+ 个点）

返回值： { type, value, unit, coordinates }

场景 ​

setSceneOptions ​

配置场景环境（雾效、大气、阴影、太阳、月亮、背景色、深度测试）。

参数类型必填默认值说明
fogEnabledboolean——启用/禁用雾效
fogDensitynumber—0.0002雾密度（0.0–1.0）
fogMinimumBrightnessnumber——最小雾亮度（0.0–1.0）
skyAtmosphereShowboolean——显示天空大气
skyAtmosphereHueShiftnumber——天空色调偏移（-1.0–1.0）
skyAtmosphereSaturationShiftnumber——天空饱和度偏移（-1.0–1.0）
skyAtmosphereBrightnessShiftnumber——天空亮度偏移（-1.0–1.0）
groundAtmosphereShowboolean——显示地面大气
shadowsEnabledboolean——启用阴影
shadowsSoftShadowsboolean——使用柔和阴影
shadowsDarknessnumber——阴影深度（0.0–1.0）
sunShowboolean——显示太阳
sunGlowFactornumber—1.0太阳光晕系数
moonShowboolean——显示月亮
depthTestAgainstTerrainboolean——地形深度测试
backgroundColorstring——背景颜色（CSS 格式）

setPostProcess ​

配置后处理效果（泛光、环境光遮蔽 SSAO、抗锯齿 FXAA）。

参数类型必填默认值说明
bloomboolean——启用泛光效果
bloomContrastnumber—128泛光对比度
bloomBrightnessnumber—-0.3泛光亮度
bloomDeltanumber—1.0泛光 delta
bloomSigmanumber—3.78泛光 sigma
bloomStepSizenumber—5.0泛光步长
bloomGlowOnlyboolean——仅显示光晕
ambientOcclusionboolean——启用环境光遮蔽（SSAO）
aoIntensitynumber—3.0AO 强度
aoBiasnumber—0.1AO 偏差
aoLengthCapnumber—0.26AO 长度上限
aoStepSizenumber—1.95AO 步长
fxaaboolean——启用 FXAA 抗锯齿

其他 ​

playTrajectory trajectory ​

沿路径播放动画。

参数类型必填默认值说明
coordinatesnumber[][]✅—路径坐标 [[lon, lat, alt?], ...]
idstring—自动轨迹图层 ID
namestring——名称
durationSecondsnumber—10动画时长（秒）
trailSecondsnumber—2尾迹长度（秒）
labelstring——移动体标签

addHeatmap heatmap ​

从点数据创建热力图。

参数类型必填默认值说明
dataobject✅—GeoJSON Point FeatureCollection
radiusnumber—30影响半径（像素）

geocode geolocation ​

将地址、地标或地名转换为地理坐标（经纬度）。使用 OpenStreetMap Nominatim 免费服务，无需 API Key。支持 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY 环境变量配置代理。

参数类型必填默认值说明
addressstring✅—地址、地标或地名，如 "故宫"、"Eiffel Tower"、"东京塔"
countryCodestring——两位 ISO 国家代码限制搜索范围（如 CN、US、JP）

返回： { success, longitude, latitude, displayName, boundingBox }

MCP 资源（2 个） ​

URI描述
cesium://scene/camera当前相机状态（位置、方向）
cesium://scene/layers所有已加载图层及其元数据列表

资源为只读，AI 智能体可轮询获取以进行上下文感知决策。

环境变量 ​

变量默认值描述
CESIUM_WS_PORT9100Bridge 连接的 WebSocket 服务器端口
DEFAULT_SESSION_IDdefaultMCP 调用路由到哪个浏览器会话
CESIUM_TOOLSETS（未设置）工具集激活：省略使用默认集，all 启用全部，或逗号分隔列表
OSM_USER_AGENTcesium-mcp-runtime/1.0Nominatim geocode 请求的 User-Agent 头
CESIUM_LOCALEen工具描述语言：en（英文，默认）或 zh-CN（中文）

会话路由 ​

多个浏览器标签页可同时连接。每个 Bridge 实例使用 sessionId 注册：

标签页 1：sessionId = "project-a"
标签页 2：sessionId = "project-b"

通过 MCP URL 路由 ​

在 MCP HTTP 端点 URL 后添加 ?session=xxx，即可将所有工具调用路由到指定浏览器：

http://localhost:3216/mcp?session=project-a

推荐用于第三方集成（如 Dify），无需在提示词或工具参数中注入 sessionId。

路由优先级 ​

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

HTTP Push API ​

对于非 MCP 集成（如 FastAPI 后端），Runtime 暴露 HTTP 端点：

bash
curl -X POST http://localhost:9100/push \
  -H "Content-Type: application/json" \
  -d '{"action": "flyTo", "params": {"longitude": 2.29, "latitude": 48.86, "height": 1000}}'

公共类型 ​

ColorInput ​

typescript
type ColorInput =
  | string                        // CSS 颜色："#FF0000"、"red"、"rgba(255,0,0,0.5)"
  | { red: number; green: number; blue: number; alpha?: number }  // RGBA 0–1

MaterialInput ​

typescript
type MaterialInput =
  | ColorInput
  | {
      type: "color" | "image" | "checkerboard" | "stripe" | "grid"
      color?: ColorInput
      image?: string
      evenColor?: ColorInput
      oddColor?: ColorInput
      orientation?: "horizontal" | "vertical"
      cellAlpha?: number
    }

PositionDegrees ​

typescript
type PositionDegrees = {
  longitude: number   // 度
  latitude: number    // 度
  height?: number     // 米
}

Released under the MIT License.

Copyright © 2025 gaopengbin