Isaac Sim robot workbench

dex-isaac-mcp

サーバー独自のツール（sim_frame_robot、sim_set_backdrop、sim_record_start）を使用し、Allegroハンドの例を操作する様子をヘッドレスで録画しました。各字幕には、リクエストと、それによって実行されたツール呼び出しが表示されています。

AI エージェント（Claude Code、または任意の MCP クライアント）が、稼働中の永続的な Isaac Sim セッションを操作し、Isaac Lab のトレーニング実行を開始できる MCP サーバーです。

Kit の起動には数十秒かかります。実験のたびに新しく起動すると、時間の大半が待ち時間になります。このサーバーでは、Kit はデーモン内で一度だけ起動し、そのまま稼働し続けます。各ツール呼び出しは実行中のセッションに届くため、ゲインの変更、物理シミュレーションのステップ実行、スクリーンショットの撮影にかかる時間は、再起動ではなく1フレーム分です。

 MCP client ──stdio──▶ dex_isaac_mcp (host, plain python)
                          │  newline-delimited JSON over a Unix socket
                          ▼
                       scripts/simd.py (Isaac Lab container, Kit stays up)
                          └─ one articulation, described by a robot JSON

• あらゆる多関節ロボットに対応。 USD と小さな JSON 設定ファイルを指定して使用できます。Franka と Allegro の例が含まれています。
• 正規化された関節制御。 目標値は 0..1 で、0 は関節の下限、1 は上限を表すため、エージェントがラジアンやメートルを知っている必要はありません。
• ロボットごとの名前付きポーズ（home、fist、…）を指定でき、途中までブレンドすることもできます。
• ヘッドレスでのキャプチャと GIF 録画に対応。自動フレーミングカメラと字幕を使用できます。上の動画はこの方法で作成しました。
• プロップ： 実行中のシーンにテーブル、ボール、または USD をスポーンし、配置された位置を読み取れます。
• 計測： 関節状態、関節ごとの可動範囲と追従誤差、動作が阻害されている関節を見つける範囲テスト、1つのセッション内でのパラメーター掃引に対応しています。
• トレーニング制御： 各実行はデタッチされた docker compose run です。状態、TensorBoard のスカラー値、チェックポイント、ログをポーリングできます。

他の Isaac Sim MCP サーバーとの違い

NVIDIA の公式 Isaac Sim MCP はコーディングアシスタント向けのドキュメント検索機能で、このサーバーと併用できます。isaacsim-mcp-server や omni-mcp/isaac-sim-mcp のようなサーバーは Isaac Sim の GUI 内で動作し、幅広いシーン構築に対応しています。このサーバーは Docker 内のデーモンとしてヘッドレスで動作し、1台のロボットの調整、計測、トレーニングに特化しています。

	NVIDIA Isaac Sim MCP	GUI 内サーバー（isaacsim-mcp-server、omni-mcp）	dex-isaac-mcp
概要	ドキュメントとコードの検索	実行中の Isaac Sim 内の Kit 拡張機能	外部デーモン。Kit はコンテナー内で稼働し続けます
シミュレーションの制御	いいえ	はい	はい
ヘッドレス／リモート GPU マシン	該当なし	GUI が必要	はい：ヘッドレスキャプチャ、Docker、Unix ソケット
シーン構築（ライト、マテリアル、センサー、アセットライブラリ）	該当なし	幅広く対応	最小限：プリミティブと USD プロップ
ロボットのセットアップ	該当なし	ロボットライブラリを内蔵	任意の USD と小さな JSON 設定ファイル（関節、ポーズ、カップリング、ゲイン）
計測	該当なし	関節と prim の状態	動作が阻害されている関節を見つける範囲テスト、追従誤差、元の値に戻す掃引
ライブ調整	該当なし	ドキュメントに記載なし	PD ゲイン、エフォート、ソフトウェアによる模倣カップリング
Isaac Lab のトレーニング	該当なし	ドキュメントに記載なし	開始、ポーリング、TensorBoard メトリクス、チェックポイント、停止
録画	該当なし	カメラキャプチャ	自動フレーミングカメラによる、字幕付き GIF のヘッドレス録画
プラットフォーム	任意	Isaac Sim を実行できる環境	Linux、NVIDIA GPU、Docker、NGC

GUI 内サーバーを選ぶ場合： 幅広いロボットとアセットライブラリを使い、対話しながらシーンを構築できます。

このサーバーを選ぶ場合： エージェントに特定のロボット（USD から作成した独自のロボットを含む）の調整、デバッグ、トレーニングを任せられます。無人環境やリモートマシンでも実行でき、スクリーンショットだけでなく、エージェントが操作に使える数値を取得できます。

要件

• Isaac Sim がサポートする NVIDIA GPU を搭載した Linux と、NVIDIA Container Toolkit
• Compose プラグインを含む Docker
• Isaac Lab イメージをプルするための NGC ログイン：docker login nvcr.io（ユーザーは $oauthtoken、パスワードは NGC API キー）
• ホスト上の Python ≥ 3.10（MCP サーバー専用）

クイックスタート

git clone <this repo> dex-isaac-mcp && cd dex-isaac-mcp

# 1. Build the image (Isaac Lab 2.3.2 base, pinned by digest)
cd docker && docker compose build && cd ..

# 2. Install the host-side server, editable so it finds this clone
pip install -e .            # add [metrics] for train_metrics: pip install -e '.[metrics]'

# 3. Register it with Claude Code
claude mcp add isaac -- python -m dex_isaac_mcp

# 4. Allow the container to open windows (once per login; needed for screenshots)
xhost +local:docker

次に、エージェントに 「Franka でシミュレーションを開始して、レディ状態に移動し、スクリーンショットを見せてください」 のように頼んでください。エージェントは sim_up、sim_set_pose、sim_step、sim_screenshot を呼び出します。

PyPI からインストールする場合： pip install dex-isaac-mcp。デーモンは引き続きクローンから実行されます（docker/ と scripts/simd.py が必要です）。そのため、サーバーからその場所を指定してください。

claude mcp add isaac -e ISAAC_MCP_HOME=/abs/path/dex-isaac-mcp -- dex-isaac-mcp

ほかの MCP クライアントでは、stdio 経由で python -m dex_isaac_mcp（または dex-isaac-mcp スクリプト）を起動できます。

最初の sim_up には数分かかります。Kit がシェーダーキャッシュを構築し、Nucleus アセットをダウンロードするためです。2 回目以降の起動は大幅に速くなります。

デーモンを手動で実行する

デーモンの終了時に sim_up はコンテナを削除する（--rm）ため、起動時にクラッシュするとトレースバックも失われます。エラーを確認するには、デーモンをフォアグラウンドで実行してください。

cd docker
docker compose run --rm simd scripts/simd.py --gui --robot examples/robots/franka.json
docker compose run --rm simd scripts/simd.py --headless --usd /path/in/container/robot.usd
docker compose run --rm simd scripts/simd.py --sliders --robot examples/robots/allegro_hand.json

--sliders を指定すると、操作対象の各関節に 1 つずつスライダーを備えた omni.ui パネルが開きます。ソケットはパネルと並行して稼働し続けます。

ツール

セッション

ツール	機能
sim_status	デーモンが起動しているかどうかと、ロボット、操作対象の関節、ポーズ、カップリング、ゲインを表示します
sim_up	デーモンコンテナ（robot、usd、gui、ground、extra_args）を起動し、応答があるまで待機します。すでに起動している場合は何もしません
sim_down	デーモンを停止します
sim_reload	スポーン設定（ロボット、USD、pos_iters、自己衝突）を変更して再起動します
sim_reset	数フレームで実験を取り消します。プロップを削除し、スポーン時のゲインとカップリングを復元して、関節とルートをスポーン時の状態に戻します。ok=False は再読み込みが必要なことを意味します

検査

ツール	機能
sim_inspect_joints	USD のアーティキュレーション DOF、アーティキュレーションから除外されているループ閉鎖関節、およびアーティキュレーションルートを表示します。ファイルを読み取るため、GUI から保存した編集内容も反映されます
sim_get_joint_state	位置と速度、および操作対象の関節の正規化された位置とリミットを表示します
sim_get_stats	最後のリセット以降の関節ごとの移動量と平均追従誤差を表示します
sim_screenshot	ビューポートの画像をキャプチャして返します。gui=True が必要です
sim_set_camera	ビューポートのカメラを向けます

操作

ツール	機能
sim_set_targets	正規化された目標値を、ベクトル全体または {joint: value} で設定します
sim_list_poses / sim_set_pose	ロボット設定にある名前付きポーズを扱います。amount は、下限値または現在の目標値からポーズに向けてブレンドします
sim_step	N 回の物理ステップを進めます（デフォルトの dt は 1/120 s）
sim_play	連続実行または一時停止します
sim_wave	操作対象の各関節を可動範囲内で動かし、移動統計を返します
sim_range_test	各関節を下限値から目標値に向けて動かし、到達した移動量の割合を報告します。0.9 未満の場合は、動きが阻害されていると判定されます（自己衝突、リンク機構の固着、トルク不足）

シーン

ツール	機能
sim_spawn_object	cuboid、sphere、cylinder、capsule、cone または USD ファイルを、衝突判定付きのプロップとして実行中のシーンに追加します。固定されたテーブルや壁には static、接触しても動かない剛体には kinematic を指定します
sim_list_objects	各プロップの現在のワールドポーズを表示します
sim_remove_object	プロップを削除します

キャプチャと記録

これらは GUI やビューポートなしでヘッドレス動作します。GUI のビューとは独立した専用カメラを使用します。

ツール	機能
sim_frame_robot	指定した方向からロボット全体がフレームに収まるように、キャプチャカメラの向きを調整します。raise_frac を指定すると、キャプション用の余白ができます
sim_set_capture_camera	キャプチャカメラを手動で配置します
sim_set_backdrop	ロボットの背後に無地の色付きパネルを配置します。映像をすっきりさせるには、ground=False と併用します
sim_capture	1 フレームを画像として返します
sim_record_start / sim_record_caption / sim_record_stop	N 回ごとの物理ステップを記録し、各フレームにキャプションを描画して、.cache/recordings/ にアニメーション GIF を保存します。シミュレーションを進める処理はすべて記録されます

調整

ツール	機能
sim_set_params	駆動関節の stiffness / damping / effort を実行中に設定します
sim_set_coupling	フォロワー関節ごとに、ソフトウェア上のミラー比を実行中に設定します
sim_sweep	1 つの実行中パラメーター（stiffness、damping、effort、coupling:<follower>）の複数の値を試し、それぞれについて wave または range を実行します。その後、元の値に戻します。ソルバーの発散はエラーとして発生させず、結果として記録します

トレーニング

ツール	機能
train_start	独自のコンテナーでヘッドレスのトレーニングを開始し、すぐに制御を返します。extra_args はスクリプトにそのまま渡されます（例：Hydra のオーバーライド）。device で使用する GPU を指定します
train_list	実行中および最近の実行と、チェックポイントを含むログディレクトリを一覧表示します
train_status	コンテナーの状態、チェックポイント、最新のスカラー値を表示します
train_logs	実行中のコンテナーの出力を末尾から表示します
train_metrics	TensorBoard のタグを一覧表示するか、1 つのタグのダウンサンプリングされた系列を取得します
train_checkpoints	ステップ数とサイズとともにチェックポイントを表示します
train_stop	実行を停止します

トレーニング実行はデーモンや MCP セッションに依存しません。クライアントが切断された後も実行を続けます。

ロボット設定

ロボット設定は 1 つの JSON ファイルです。必須なのは usd だけです。不明なキーは拒否されるため、タイプミスはデフォルト値にひそかにフォールバックするのではなく、明確にエラーになります。

{
  "name": "franka",
  "usd": "{ISAACLAB_NUCLEUS_DIR}/Robots/FrankaEmika/panda_instanceable.usd",
  "fix_root_link": true,
  "spawn_pos": [0, 0, 0],
  "init_joint_pos": {"panda_joint4": -2.81, "panda_joint6": 3.04, ".*": 0.0},
  "driven_joints": ["panda_joint[1-7]", "panda_finger_joint.*"],
  "passive_joints": [],
  "couplings": [{"leader": "joint_a", "follower": "joint_b", "ratio": 1.0}],
  "actuator": {"stiffness": 400, "damping": 40, "effort": 87, "velocity": null},
  "solver": {"pos_iters": 32, "vel_iters": 4, "self_collisions": true},
  "camera": {"eye": [1.8, 1.8, 1.4], "target": [0, 0, 0.4]},
  "poses": {"ready": {"panda_joint[1357]": 0.5, "panda_finger_joint.*": 1.0}}
}

キー	意味
usd	ローカルパス（相対パスは JSON ファイル自身のディレクトリを基準に解決されます）、URL、または {ISAAC_NUCLEUS_DIR} / {ISAACLAB_NUCLEUS_DIR} を使用するパス
init_joint_pos	関節固有の単位（rad / m）で指定するスポーン姿勢。正規表現をキーにします。すべての関節のリミット内でなければ、スポーンに失敗します。 デフォルトはすべてゼロです。たとえば Franka の関節 4 では範囲外になります
driven_joints	コマンドを受け取る関節の正規表現（完全一致）。デフォルトは .*
passive_joints	閉ループリンク機構など、角度が拘束によって決まる関節です。実行中の PD 駆動は拘束と競合して機構が振動するため、剛性ゼロの駆動が適用されます
couplings	ソフトウェアによるミラー関節です。フォロワーの目標値 = ratio × リーダーの目標値。PhysX のミラー拘束ではなく駆動目標値として適用するため、大きな比率でもソルバーが不安定になりません
actuator	駆動関節の暗黙的な PD ゲインと努力量／速度のリミットです。実行中に調整できます
solver	スポーン時のプロパティです。変更するには sim_reload が必要です
poses	{name: {joint_regex: 0..1}}。後に指定したパターンが優先されるため、{".*": 0, "thumb.*": 1} のように指定できます。駆動関節に一致しないパターンはエラーになります

フォークせずに独自のロボットを使用する

ロボット設定とアセットは独自のリポジトリに保持し、COMPOSE_FILE に指定する Compose オーバーライドを使ってコンテナーに追加します。絶対パスを使用して、MCP サーバーの環境変数に設定してください。

# my-robot/mcp-compose.yaml
services:
  simd:
    volumes:
      - /abs/path/my-robot:/workspace/my-robot

claude mcp add isaac \
  -e COMPOSE_FILE=/abs/path/dex-isaac-mcp/docker/docker-compose.yaml:/abs/path/my-robot/mcp-compose.yaml \
  -e ISAAC_MCP_ROBOT=/workspace/my-robot/robot.json \
  -- python -m dex_isaac_mcp

学習のデフォルト設定

初期状態では、train_start は isaac-lab サービス内で Isaac Lab の標準 skrl スクリプトを実行します。実行名をログディレクトリ（logs/skrl/<experiment>/<timestamp>_ppo_torch_<run_name>/）に付加します。このディレクトリは、ほかの train_* ツールが実行を見つけるために使用します。独自のランチャーを使う場合は、MCP サーバーの起動環境で次の変数を設定してください。

Variable	Default
ISAAC_MCP_HOME	このパッケージのインストール元であるクローン（編集可能インストール）。PyPI からインストールした場合は 必須 です
ISAAC_MCP_COMPOSE_DIR	<repo>/docker
ISAAC_MCP_TRAIN_SERVICE	isaac-lab
ISAAC_MCP_TRAIN_WORKDIR	/workspace/isaaclab
ISAAC_MCP_TRAIN_SCRIPT	scripts/reinforcement_learning/skrl/train.py
ISAAC_MCP_LOGS_DIR	<repo>/logs（/workspace/isaaclab/logs にマウント）
ISAAC_MCP_RUN_NAME_ARG	agent.agent.experiment.experiment_name={run_name}（空の場合、渡しません）
ISAAC_MCP_TRAIN_ARGS	hydra.run.dir=/tmp/hydra hydra.output_subdir=null：すべての実行に追加します。標準スクリプトはこれを指定しないと、Hydra の outputs/ を root 所有の /workspace/isaaclab に書き込み、失敗します。Hydra を使わないスクリプトでは空に設定してください
ISAAC_MCP_SIMD_SERVICE	simd
ISAAC_MCP_ROBOT	sim_up でロボットが指定されていない場合に読み込むロボット設定（未設定時は Franka の例）
ISAAC_MCP_SOCKET	<repo>/.cache/simd.sock

スクリプトは --task、--headless を受け付ける必要があります。また、指定された場合は --num_envs、--seed、--max_iterations、--checkpoint も受け付ける必要があります。独自の拡張機能のタスクは、コンテナ内でインポートできるように、イメージにインストールするかマウントしてください。

設計上の注意事項

以下は、このコードの前提となる制約です。その多くは、実際に問題を起こして学んだものです。

• Kit の呼び出しはすべてメインスレッドで行います。 Kit、PhysX、USD はスレッドセーフではありません。ソケットスレッドは JSON の解析とリクエストのキュー登録のみを行い、メインループが物理ステップの合間にリクエストを実行します。リーダースレッドから応答すると一見うまく動くように見えますが、負荷がかかるとステージが破損します。
• スポーン時のプロパティは固定されます。 スポーン済みのアーティキュレーションを置き換えるには SimulationContext.stop() が必要ですが、これは Kit ループが処理を進めている間だけ進行するタイムラインイベントを待機するため、ブロックします。コマンドはそのループ上で実行されるため、呼び出しは戻りません。omni.usd の new_stage() も同じ問題があります。そのため、USD、ソルバーの反復回数、自己衝突には再起動（sim_reload）が必要ですが、ゲインは実行中に変更できます。実験の取り消しでは対応できません。sim_reset を実行すると、数フレーム後にスポーン時の状態に戻ります。
• TCP ではなく Unix ソケットを使用します。 リポジトリはバインドマウントされ、コンテナはホストの uid で実行されるため、ポートマッピングなしでホストからソケットファイルを直接参照できます。パスの上限は 107 バイト（AF_UNIX）です。チェックアウト先のパスが深い場合は、ISAAC_MCP_SOCKET を設定してください。
• ホスト側では Isaac のコードをインポートしません。 protocol.py、robot.py、training.py は標準ライブラリのみを使用します。MCP サーバーが追加で使用するのは mcp だけです。ホストに isaaclab、torch、GPU は必要ありません。
• キャッシュディレクトリは .gitkeep とともにコミットされています。 Docker がバインドマウント元を自動作成すると、そのディレクトリは root の所有になり、Kit はスクリプトの実行前に registry cache path is not set で終了します。
• ベースイメージはダイジェストで固定されています。 以前、タグを再取得した際に /isaac-sim のモードが 750 で配布され、root 以外で実行するすべてのコンテナで Python が使えなくなりました。
• 録画した GIF は安定化されています。 レンダラーのデノイザーにはちらつきがあります。静止したシーンの 2 フレーム間でも背景ピクセルの約 9％がわずかに変化し、GIF はそのすべてを再エンコードします。しきい値未満の変化を保持し、共通のパレットを使うことで、9 秒のクリップを 15 MB から 1.2 MB に縮小できました。
• デーモンはヘッドレスでも常にレンダリングします（enable_cameras）。レンダリングしないと、PhysX は実行中にスポーンされたプロップを登録しません。プロップのポーズは fabric から読み取ります。USD の変換と PhysX の CPU クエリはどちらもスポーン時のポーズのままになり、シミュレーション中に PhysX のテンソルビューを作成すると CUDA がクラッシュするためです。
• 範囲テストでは、リンクが地面に届く可能性のあるものに床を設置しません（ground=False）。設置すると、ロボットではなく床を測定することになります。

開発

python -m unittest discover tests   # host-side tests: no Isaac, no GPU
ruff check .

dex_isaac_mcp/protocol.Client は、デバッグに便利なクライアントです。

from dex_isaac_mcp.protocol import Client
with Client() as c:
    print(c.call("status"))
    c.call("set_pose", name="ready"); c.call("step", n=240)

ステータス

Isaac Lab 2.3.2（Isaac Sim 5.x）および mcp 2.3 に対して、GUI を起動した状態で stdio プロトコル経由でテスト済みです。

• Franka および Allegro のサンプルに加え、compose オーバーライド経由のカスタム閉リンクハンド：sim_up、ポーズ、スクリーンショット、sim_range_test、sim_sweep（元の値を復元）、sim_down。

• ヘッドレスデーモン：ゲイン、凍結パラメーターの拒否、波形。

• ヘッドレスでのキャプチャと録画（Allegro および Franka）：自動フレーミング、背景、キャプション、GIF 出力（先頭にあるクリップ）。

• プロップ、GUI およびヘッドレス：静的なテーブルに落とした球体と円柱が、それぞれ半径と高さの半分をテーブルの高さに加えた位置で正確に静止します。

• Isaac Lab 標準の skrl スクリプトを使用したトレーニング：Isaac-Cartpole-v0 を起動し、ポーリング、ログ記録、チェックポイント保存を行い、すべての train_* ツール経由で読み戻しました。また、トレーニング途中で停止した実行もテストしました。skrl の write_interval: auto は、非常に短い実行（5 イテレーション）では TensorBoard のスカラーを書き込まないため、その場合 train_metrics は空になります。50 イテレーションでは 18 個のタグが得られます。

問題の報告やプルリクエストを歓迎します。

ライセンス

MIT ライセンスです。詳しくは LICENSE を参照してください。