cesium-mcp-bridge

Browser SDK — embeds in your CesiumJS app, receives commands via WebSocket.

Installation

npm install cesium-mcp-bridge

Peer dependency: cesium@~1.143.0 || ~1.145.0

Initialization

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

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

JSON command dispatch validates shared input contracts before execution and output contracts after execution. You can override one executor while preserving all defaults:

const bridge = new CesiumBridge(viewer, {
  executors: {
    load3dTiles: async (params, bridge) => {
      return loadAuthorizedTileset(bridge.viewer, params)
    },
  },
})

Custom integrations that intentionally extend a result can set validateOutputs: false. Input validation has the equivalent validateInputs: false compatibility escape hatch.

All 60 browser-safe executors are organized by domain and checked against the shared contracts. The public execute() and override contract remain stable; the sensitive setIonToken compatibility command stays outside the shared AI tool surface.

Call bridge.dispose() when removing the integration. It cancels camera flights and pending screenshots, releases Bridge-managed activity, internal Cesium references, executors, and event handlers without destroying the application-owned Viewer or its scene content. Disposal is idempotent; later execute() calls return a disposed error.

Commands (60)

View Control

Command	Description	Key Parameters
flyTo	Animate camera to a position	longitude, latitude, height, heading, pitch, roll, duration
setView	Instantly set camera position	longitude, latitude, height, heading, pitch, roll
getView	Get current camera state	—
zoomToExtent	Zoom to geographic bounds	west, south, east, north
saveViewpoint	Save current view as named bookmark	name
loadViewpoint	Restore a saved viewpoint bookmark	name, duration
listViewpoints	List all saved viewpoint bookmarks	—
exportScene	Export scene as structured JSON snapshot	—

Entity

Command	Description	Key Parameters
addMarker	Add point marker	longitude, latitude, label, color, size
addLabel	Add text labels	data, field, style
addPolyline	Add polyline (path/route)	coordinates, color, width, clampToGround
addPolygon	Add polygon area	coordinates, color, outlineColor, opacity, extrudedHeight
addModel	Place 3D model (glTF/GLB)	longitude, latitude, url, scale, heading, pitch, roll
updateEntity	Update entity properties	entityId, position, color, label, scale, show
removeEntity	Remove a single entity	entityId
batchAddEntities	Add multiple entities at once	entities (array of typed defs)
queryEntities	Search/filter entities in scene	name, type, bbox
getEntityProperties	Get all properties of an entity	entityId

Layer Management

Command	Description	Key Parameters
addGeoJsonLayer	Load GeoJSON data	url or data, name, style
addGeoJsonPrimitive	Load large GeoJSON datasets with primitives	url or data, name, allowPicking
listLayers	List all loaded layers	—
removeLayer	Remove a layer by ID	layerId
clearAll	Remove all layers, entities, and data sources	—
setLayerVisibility	Show/hide a layer	layerId, visible
updateLayerStyle	Change layer styling	layerId, layerStyle, imageryStyle, primitiveStyle, tileStyle
getLayerSchema	Get layer property field structure	layerId
setBasemap	Switch imagery base layer	provider, url

Camera (advanced)

Command	Description	Key Parameters
lookAtTransform	Orbit-style camera aim	longitude, latitude, height, heading, pitch, range
startOrbit	Start camera orbit	speed, direction
stopOrbit	Stop orbit animation	—
setCameraOptions	Configure camera controller	enableRotate, enableZoom, enableTilt

Extended Entity Types

Command	Description	Key Parameters
addBillboard	Add image icon	longitude, latitude, image, scale
addBox	Add 3D box	position, dimensions, material
addCorridor	Add corridor	positions, width, material
addCylinder	Add cylinder/cone	position, length, topRadius, bottomRadius
addEllipse	Add ellipse	position, semiMajorAxis, semiMinorAxis
addRectangle	Add rectangle	west, south, east, north, material
addWall	Add wall	positions, maximumHeights, minimumHeights

Animation

Command	Description	Key Parameters
createAnimation	Create waypoint animation	entityId, waypoints, model
controlAnimation	Play/pause animation	entityId, action
removeAnimation	Remove animation entity	entityId
listAnimations	List active animations	—
updateAnimationPath	Update path visuals	entityId, show, width, color
trackEntity	Camera follows entity	entityId
controlClock	Configure clock	startTime, stopTime, multiplier
setGlobeLighting	Globe lighting control	enableLighting, enableFog

3D Scene

Command	Description	Key Parameters
load3dTiles	Load 3D Tileset	url or ionAssetId, name, maximumScreenSpaceError
load3dGaussianSplat	Load a 3D Gaussian Splat dataset	url, name, maximumScreenSpaceError
loadTerrain	Set terrain provider	url, provider
loadImageryService	Add imagery layer	url/serviceType or ionAssetId, name
loadCzml	Load CZML time-dynamic data	data or url, name
loadKml	Load KML/KMZ data	data or url, name
setEdgeDisplayMode	Set 3D Tiles surface/edge display	tilesetId, mode

Interaction

Command	Description	Key Parameters
screenshot	Capture current view	width, height, format
highlight	Highlight features	layerId, featureId, color
measure	Measure distance or area	type, coordinates

Other

Command	Description	Key Parameters
playTrajectory	Animate along a path	positions, duration, loop
addHeatmap	Create heatmap visualization	points, name, radius, gradient

Scene

Command	Description	Key Parameters
setSceneOptions	Configure scene environment	fogEnabled, shadowsEnabled, sunShow, backgroundColor
setPostProcess	Configure post-processing effects	bloom, ambientOcclusion, fxaa

Two Calling Styles

Style 1: Type-safe Methods

const result = await bridge.flyTo({
  longitude: 116.4,
  latitude: 39.9,
  height: 5000,
  duration: 2,
})

Style 2: JSON Command Dispatch

const result = await bridge.execute({
  action: 'flyTo',
  params: {
    longitude: 116.4,
    latitude: 39.9,
    height: 5000,
    duration: 2,
  },
})

Events

bridge.on('layerAdded', (layer) => console.log('Layer added:', layer))
bridge.on('layerRemoved', (layerId) => console.log('Removed:', layerId))
bridge.on('error', (err) => console.error('Bridge error:', err))

TypeScript Types

import type {
  BridgeCommand,
  BridgeResult,
  FlyToParams,
  SetViewParams,
  AddGeoJsonLayerParams,
  AddHeatmapParams,
  AddPolylineParams,
  AddPolygonParams,
  AddModelParams,
  UpdateEntityParams,
  RemoveEntityParams,
  Load3dTilesParams,
  PlayTrajectoryParams,
  LayerInfo,
  HighlightParams,
  ColorInput,
  // Camera
  LookAtTransformParams,
  StartOrbitParams,
  SetCameraOptionsParams,
  // Entity Types
  AddBillboardParams,
  AddBoxParams,
  AddCorridorParams,
  AddCylinderParams,
  AddEllipseParams,
  AddRectangleParams,
  AddWallParams,
  MaterialSpec,
  MaterialInput,
  OrientationInput,
  PositionDegrees,
  // Animation
  CreateAnimationParams,
  ControlAnimationParams,
  RemoveAnimationParams,
  UpdateAnimationPathParams,
  TrackEntityParams,
  ControlClockParams,
  SetGlobeLightingParams,
  AnimationWaypoint,
  AnimationInfo,
  // Layer Schema & Style
  GetLayerSchemaParams,
  LayerSchemaResult,
  LayerSchemaField,
  UpdateLayerStyleParams,
  // Scene
  SetSceneOptionsParams,
  SetPostProcessParams,
  // Data Formats
  LoadCzmlParams,
  LoadKmlParams,
  // Interaction
  MeasureParams,
} from 'cesium-mcp-bridge'