Isaac Sim robot workbench

dex-isaac-mcp

使用服务自身的工具（sim_frame_robot、sim_set_backdrop、sim_record_start）进行无头录制，驱动 Allegro 灵巧手示例。每条字幕都是请求及其对应的工具调用。

一个 MCP 服务，可让 AI Agent（Claude Code 或任何 MCP 客户端）驱动实时、持久运行的 Isaac Sim 会话并启动 Isaac Lab 训练任务。

Kit 启动需要几十秒。如果每次实验都要重新启动，大部分时间都会耗在等待上。这里，Kit 在守护进程中启动一次后便会持续运行。每次工具调用都会在该运行中的会话内执行，因此调整增益、推进物理模拟或截图只需一帧，而无需重新启动。

 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 表示关节上限，因此 Agent 无需了解弧度或米。
• 每个机器人都有命名姿势（home、fist……），并且可以按比例混合。
• 无头捕获和 GIF 录制，使用自动取景的摄像头并添加字幕。上方的片段就是这样制作的。
• 道具： 在运行中的场景里生成桌子、球或 USD，并读取它们最终停留的位置。
• 测量： 关节状态、每个关节的行程和跟踪误差、用于查找受阻关节的范围测试，以及在单个会话中进行参数扫描。
• 训练控制： 每次运行都会启动一个脱离终端的 docker compose run。你可以轮询其状态、TensorBoard 标量、检查点和日志。

与其他 Isaac Sim MCP 服务的区别

NVIDIA 官方 Isaac Sim MCP 是面向编码助手的文档搜索工具，可以与本服务配合使用。像 isaacsim-mcp-server 和 omni-mcp/isaac-sim-mcp 这样的服务运行在 Isaac Sim GUI 内，广泛支持场景构建。本服务以 Docker 中的守护进程形式无头运行，专注于对单个机器人进行调优、测量和训练。

	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 内服务，即可通过交互式对话构建场景，并使用丰富的机器人和资产库。

选择本服务，即可让 Agent 对特定机器人（你自己的 USD 机器人）进行调优、调试和训练；可以无人值守运行，也可以在远程主机上运行，并获取可供其采取行动的数据，而不仅仅是截图。

要求

• 配备 Isaac Sim 支持的 NVIDIA GPU 的 Linux 系统，以及 NVIDIA Container Toolkit
• 安装了 Compose 插件的 Docker
• 登录 NGC 以拉取 Isaac Lab 镜像：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

然后向 Agent 提出类似 “启动仿真，加载 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 资源。后续启动会快得多。

手动运行守护进程

守护进程退出时，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 会打开一个 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 的关节结构自由度、不属于关节结构的闭环关节，以及关节结构根节点。此工具会读取文件，因此会显示从 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	捕获单帧并以图像形式返回
sim_record_start / sim_record_caption / sim_record_stop	每隔 N 个物理步录制一帧，并在每帧绘制字幕，生成动画 GIF，保存到 .cache/recordings/。所有会推进仿真的操作都会被录制

调优

工具	功能
sim_set_params	实时设置驱动关节的 stiffness / damping / effort
sim_set_coupling	实时设置软件模仿比例，以从动关节为键
sim_sweep	尝试某个实时参数（stiffness、damping、effort、coupling:<follower>）的多个值，并针对每个值运行 wave 或 range。之后恢复原始值。如果求解器发散，会将其记录为结果，而不是抛出错误

训练

工具	功能
train_start	在独立容器中启动无头训练任务并立即返回。extra_args 会原样传递给脚本（例如 Hydra 覆盖参数）。device 用于指定 GPU
train_list	正在运行和近期的任务，以及存放检查点的日志目录
train_status	容器状态、检查点和最新标量数据
train_logs	查看运行中容器输出的末尾内容
train_metrics	列出 TensorBoard 标签，或获取某个标签的降采样序列
train_checkpoints	查看检查点及其步数和大小
train_stop	停止任务

训练任务不依赖守护进程或 MCP 会话。即使客户端断开连接，训练仍会继续。

机器人配置

机器人由一个 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 覆盖文件将其添加到容器中，然后在 COMPOSE_FILE 中列出该文件。在 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 服务启动时所处的环境中设置以下变量：

变量	默认值
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 会在几帧内将生成状态写回。
• 使用 Unix 套接字，而非 TCP。 仓库会绑定挂载，容器以主机 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 已做稳定处理。 渲染器的降噪器会产生闪烁：静止场景的两帧之间，约有 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 上通过 stdio 协议进行测试，GUI 已开启：

• 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 个标签。

欢迎提交问题和 PR。

许可证

MIT，详见 LICENSE。