Cesium Mcp Runtime

cesium-mcp-runtime

使用状況の統計はデフォルトで有効で、起動時に stderr に通知が表示されます。無効にするには、CESIUM_TELEMETRY_DISABLED=1 または DO_NOT_TRACK=1 を設定するか、--no-telemetry を渡してください。収集される項目とプライバシー。

英語 | 中国語

Model Context Protocol を介して、AI エージェントが Cesium 地球儀をリアルタイムに操作できるようにする MCP サーバーです。

リリースチャネル：latest は安定版の MCP SDK v2 を使用し、同じ stdio/HTTP エントリーポイントから MCP 2025-11-25 と 2026-07-28 の両方をサポートします。 「AI + Cesium」の使用感を試してみたいだけの場合は、 examples/browser-agent を出発点としておすすめします。バックエンドは不要で、3 分で実行できます。どのモードを使うべきですか？をご覧ください。

MCP Apps マップパネル

openCesiumMap は、標準の ui://cesium-mcp/map-v10.html MCP Apps リソースを通じて、インタラクティブな Cesium Viewer を提供します。マップはメイン領域を占め、ui/message を介してホスト既存のネイティブチャットを使用するため、入力欄や履歴が重複することはありません。レイアウトやホストのテーマ／ロケールが変更されても、Viewer、選択状態、セッションは維持されます。アプリはホストのセマンティックスタイル変数とフォントに準拠し、中国語と英語に対応しており、カメラ、レイヤー、選択オブジェクトのコンテキストを公開します。ローカルプレビューコントロールでは、ホストのライブ設定をシミュレートし、メッセージの配信を記録できます。OpenAI のグローバル／スレッドエントリーポイントと全画面表示のヒントも含まれています。

ビルド済み HTML、埋め込み Worker グラフ、Bridge バンドルは dist に含まれます。互換性のあるホストには、分離された安定した UI オリジンでの WebGL と Blob モジュールワーカーのサポートが必要です。埋め込みパネルは、アプリ専用の 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/ を開いてください。ガイド全文をご覧ください。ChatGPT 固有のクライアントへのインストールは、別途検証する必要があります。

ベクタータイル

CESIUM_TOOLSETS=view,entity,layer,interaction,tiles を設定するか、enable_toolset を使って tiles ツールセットを有効にします。MVT の /{z}/{x}/{y} URL またはベクター 3D Tiles には loadVectorTiles を使います。地物をクリックして 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 ユーザーの場合、これは 1 つのパッケージで完結する構成です。cesium-mcp-runtime を実行して、組み込み Viewer を使用してください。カスタムの CesiumJS ページを開発する場合に限り、cesium-mcp-bridge を別途インストールします。

2 つのトランスポートモードに対応しています。

トランスポート	用途	プロトコル
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 モードでは、Cesium コマンドツール 62 個すべてがデフォルトで有効になります（動的なツールセットの検出は不要です）。

MCP クライアントの設定

ネットワークアクセス

ランタイムは、HTTP ポートと WebSocket ポートを含め、デフォルトで 127.0.0.1 にバインドします。 ローカルのネイティブ 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 は接続トークンの入力を求め、トークンはページ内にのみ保持します。カスタムブラウザーブリッジでは、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 のアップグレードには引き続きトークンが必要です。2 つ目以降のローカル 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 エージェントが動的に有効化できます。共通のタイトル、動作に関する注釈、ローカライズされた説明、デフォルト値、入力検証、提示される出力スキーマ、および構造化された結果は、cesium-mcp-contracts の正規 JSON Schemas から生成されます。ツール呼び出しでは、古いクライアント向けにテキストの content も保持されます。

ツールセットの概要

ツールセット	ツール数	デフォルト	説明
view	8	はい	カメラビューの制御＋視点のブックマーク＋シーンのエクスポート
entity	10	はい	エンティティの基本操作＋一括処理、クエリ、プロパティの検査
layer	9	はい	レイヤー管理（GeoJSON、スキーマ、スタイル、ベースマップ）
interaction	3	はい	スクリーンショット、ハイライト、計測
camera	4	—	高度なカメラ制御（オービット、lookAt）
entity-ext	7	—	拡張エンティティタイプ（ボックス、シリンダー、壁など）
animation	8	—	アニメーションシステム（ウェイポイント、クロック、トラッキング、ライティング）
tiles	7	—	3D Tiles、Gaussian Splats、地形、画像サービス、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 が必要に応じて追加機能を見つけて有効化できるよう、2 個のメタツールが常に利用可能です。

ツール	説明
list_toolsets	有効状態とツール名を含む、すべてのツールセットグループを一覧表示
enable_toolset	ツールセットを動的に有効化 — 新しいツールがすぐに利用可能になります

View

ツール	説明
flyTo	座標（lon、lat、height、heading、pitch、roll、duration）へ移動
setView	カメラの位置を即座に設定
getView	現在のカメラ状態を取得
zoomToExtent	バウンディングボックス（west、south、east、north）にズーム

Entity

ツール	説明
addMarker	座標位置にマーカーを追加
addLabel	マップにテキストラベルを追加
addModel	3D モデル（glTF/GLB または Ion アセット）を追加
addPolygon	スタイルを指定してポリゴンを追加
addPolyline	スタイルを指定してポリラインを追加
updateEntity	エンティティのプロパティを更新
removeEntity	ID を指定してエンティティを削除

Layer

ツール	説明
addGeoJsonLayer	スタイル（コロプレス、カテゴリなど）を指定して GeoJSON を追加
listLayers	すべてのレイヤーを一覧表示
removeLayer	ID を指定してレイヤーを削除
setLayerVisibility	レイヤーの表示／非表示を切り替え
updateLayerStyle	レイヤーの色、不透明度、幅を変更
setBasemap	ベースマップを切り替え

Camera (ツールセット: camera)

ツール	説明
lookAtTransform	指定位置にカメラを向けるオービット式の操作（heading/pitch/range）
startOrbit	現在の中心点の周りでカメラのオービットを開始
stopOrbit	オービットアニメーションを停止
setCameraOptions	カメラコントローラーを設定（回転、ズーム、傾斜の有効化／無効化）

拡張エンティティタイプ (toolset: entity-ext)

ツール	説明
addBillboard	位置に画像アイコンを追加します
addBox	寸法とマテリアルを指定して3Dボックスを追加します
addCorridor	回廊（幅のあるパス）を追加します
addCylinder	円柱または円錐を追加します
addEllipse	楕円（オーバル）を追加します
addRectangle	地理的な境界を指定して長方形を追加します
addWall	位置に沿って壁を追加します

アニメーション (toolset: animation)

ツール	説明
createAnimation	ウェイポイントを使用した時間ベースのアニメーションを作成します（エンティティをパスに沿って移動）
controlAnimation	現在のアニメーションを再生または一時停止します
removeAnimation	アニメーションエンティティを削除します
listAnimations	アクティブなアニメーションをすべて一覧表示します
updateAnimationPath	アニメーションパスの視覚プロパティを更新します
trackEntity	カメラでエンティティを追跡します
controlClock	Cesium クロックを設定します（時間範囲、速度、アニメーション状態）
setGlobeLighting	地球の照明と大気効果を有効化／無効化します

タイルとデータ (toolset: tiles)

ツール	説明
load3dTiles	URL または Ion アセット ID から3D Tilesを読み込みます
loadTerrain	地形プロバイダーを設定します
loadImageryService	画像サービス（WMS／WMTS／XYZ／Ion）を追加します

インタラクション (toolset: 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 を使って1つのランタイムに接続できます：

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 Push 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