Isaacsim Mcp Server

Isaac Sim MCP 服务

通过 Model Context Protocol（MCP）使用自然语言控制 NVIDIA Isaac Sim。

将任何兼容 MCP 的 IDE（Cursor、VS Code、Claude Code、Windsurf、Antigravity、JetBrains）连接到正在运行的 Isaac Sim 实例，并通过自然语言提示词进行控制——创建机器人、构建场景、运行仿真，以及直接在编辑器中调试物理效果。

主要功能

• 43 个工具，涵盖 9 个类别——场景、对象、照明、机器人、传感器、材质、资产、仿真、图
• 从 Isaac Sim 资产库自动发现 107+ 款机器人（Franka、UR、Unitree、Boston Dynamics 等）
• 逐步执行并观察调试——单次调用即可逐步运行仿真，并检查 prim 位置、关节状态和物理效果
• 热重载——无需重启 Isaac Sim，即可迭代 Python 控制器
• 多实例——在不同端口并行运行多个 Isaac Sim 会话
• 适用于 Isaac Sim 5.1.0 - 6.0.1（PhysX + Newton），并提供用于隔离不同版本的模块化适配器层

安装

选项 A：使用 pip 安装（推荐）

pip install isaacsim-mcp-server

这会安装 MCP 服务和 isaacsim-mcp-server CLI。你仍需从仓库安装 Isaac Sim 扩展（请参阅下方的启动 Isaac Sim）。

选项 B：从源代码安装

git clone https://github.com/whats2000/isaacsim-mcp-server
cd isaacsim-mcp-server
./scripts/setup_python_env.sh

要求

重要

支持 Linux 和 Windows。在 Windows 上，请使用 PowerShell 启动脚本 scripts/run_isaac_sim.ps1 替代 .sh 脚本（见下文）。 不支持 macOS，因为 NVIDIA Isaac Sim 无法在 macOS 上运行。

说明

欢迎提交贡献，以支持其他 Isaac Sim 版本。 适配器层经过设计，便于隔离不同版本。

快速开始

1. 设置环境

如果你是从源代码安装：

./scripts/setup_python_env.sh

在 Windows 上，uv sync 会创建虚拟环境（.venv），并安装 该软件包及其依赖项：

uv sync

2. 使用扩展启动 Isaac Sim

./scripts/run_isaac_sim.sh

你应该会在日志中看到：

Registered 43 command handlers
Isaac Sim MCP server started on localhost:8766

脚本会在 $HOME/isaacsim 中查找 Isaac Sim；如需使用其他安装位置，请设置 ISAACSIM_ROOT。

选择物理引擎。 Isaac Sim 6.0+ 提供 PhysX（默认）和 Newton 后端。使用 --newton / --physx 或 ISAACSIM_ENGINE 进行选择：

./scripts/run_isaac_sim.sh                  # PhysX (default)
./scripts/run_isaac_sim.sh --newton         # Newton
ISAACSIM_ENGINE=newton ./scripts/run_isaac_sim.sh

script/launch_isaac_sim_mcp.sh 也支持相同的标志。命令行中的其他参数会原样传递给 Kit。服务会自动检测当前使用的引擎，因此无需更改 MCP 端的配置。Newton 需要 6.0 或更高版本；在 5.1.0 上请求使用 Newton 时，会显示明确的错误消息。

在 Windows 上，请改用 PowerShell 启动器。它支持相同的引擎选择，并会将额外参数传递给 Kit：

.\scripts\run_isaac_sim.ps1                          # PhysX (default)
.\scripts\run_isaac_sim.ps1 -Engine newton           # Newton
$env:ISAACSIM_ENGINE = 'newton'; .\scripts\run_isaac_sim.ps1

脚本会依次从 -IsaacSimRoot、$env:ISAACSIM_ROOT、本地源码构建目录、C:\isaacsim 和 %USERPROFILE%\isaacsim 中确定安装位置。它还会创建可写的 USD 工作目录（.cache\usd），因为 Windows 没有 /tmp。

export BEAVER3D_MODEL="<your beaver3d model name>"
export ARK_API_KEY="<your beaver3d api key>"
export NVIDIA_API_KEY="<your nvidia api key>"

$env:BEAVER3D_MODEL = "<your beaver3d model name>"
$env:ARK_API_KEY = "<your beaver3d api key>"
$env:NVIDIA_API_KEY = "<your nvidia api key>"

3. 连接 IDE

将 MCP 服务添加到编辑器中。将路径替换为实际的仓库位置。command 示例适用于 Linux/macOS；各指南中也提供 Windows 对应配置，该配置会调用 PowerShell 启动器 scripts\run_mcp_server.ps1。

claude mcp add isaac-sim /path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

claude mcp add isaac-sim -- powershell -NoProfile -ExecutionPolicy Bypass -File C:\path\to\isaacsim-mcp-server\scripts\run_mcp_server.ps1

{
  "mcpServers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

{
  "servers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

{
  "servers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    }
  }
}

{
  "mcpServers": {
    "isaac-sim": {
      "command": "powershell",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\isaacsim-mcp-server\\scripts\\run_mcp_server.ps1"]
    }
  }
}

4. 开始输入提示词

Check the connection with get_scene_info.
If the scene is empty, create a physics scene.
Add a Franka robot at the origin and a Go1 quadruped at [2, 0, 0].

架构

MCP Client (IDE)
      |
      v
isaacsim-mcp-server          (PyPI package / CLI)
      |
      v  TCP socket (localhost:8766)
      |
isaac.sim.mcp_extension      (Omniverse extension)
      |
      v
Handlers -> Adapter -> Isaac Sim 5.1 / 6.0 APIs

工具

9 个类别共 43 个工具：

已知限制

常规会话中可能遇到的未解决缺陷。对于可能的情况，系统会在使用时发出警告；此列表用于帮助你在启动前选择运行时。

示例提示词

场景初始化

Check the connection with get_scene_info. If the scene is empty, create a physics scene.
Add stronger lighting and place a camera that looks at the workspace.

机器人布局

Create three Franka robots in a row at [0,0,0], [2,0,0], and [4,0,0].
Then add a Go1 robot at [1, 3, 0].

环境加载

List available environments, choose a warehouse-like one, and load it.
Create a camera and capture an image.

资产搜索和 3D 生成

Search for a rusty desk, load the best result near [0, 5, 0], scaled to [2, 2, 2].

高级用法

多个实例

并行运行多个 Isaac Sim 会话。每个会话使用不同的端口（从 8766 自动分配）。

# First instance (default port 8766)
claude mcp add isaac-sim /path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh

# Second instance (port 8767)
claude mcp add isaac-sim-2 -e ISAAC_MCP_PORT=8767 -- /path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh

{
  "mcpServers": {
    "isaac-sim": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh"
    },
    "isaac-sim-2": {
      "command": "/path/to/isaacsim-mcp-server/scripts/run_mcp_server.sh",
      "env": { "ISAAC_MCP_PORT": "8767" }
    }
  }
}

桌面启动器（Linux）

安装专用的 Isaac Sim MCP 应用图标：

./scripts/install_desktop_entry.sh

这会创建一个启动器，可自动分配端口、等待扩展套接字就绪，并在退出时清理。

推荐工作流

1. 使用 get_scene_info 验证连接
2. 如果舞台为空，则创建物理场景
3. 优先使用专用工具，而不是 execute_script
4. 加载前使用 list_available_robots / list_environments
5. 使用 create_action_graph 将 OnPlaybackTick → ScriptNode 控制器连接起来
6. 使用 step_simulation，并搭配 observe_prims 和 observe_joints 进行调试
7. 使用 reload_script 迭代控制器，无需重启

演示：Franka 抓取与放置

demo/franka_pick_place.py 中提供了一个可直接运行的演示，使用 RMPflow 进行运动规划：

Please use the Isaac MCP tool complete this:

Create a physics scene with a ground plane, then spawn a Franka FR3 robot at the origin.

Add two textured tables with a gap along Y. Place a small textured cube with physics enabled on top of the first table.

Use `create_action_graph` to wire `OnPlaybackTick` → `ScriptNode`, and write a pick-and-place controller script using RMPflow for motion planning. Save the script to the `demo/` directory.

Use `get_prim_info` to query actual positions and sizes of the tables and cube before writing the controller — do not hardcode coordinates.

Start the simulation with Play. The robot should pick the cube from table 1 and place it on table 2. Verify the process using `step_simulation` with `observe_prims` on the cube to confirm it reaches table 2.

使用 create_action_graph 搭配 script_file，一步完成 Action Graph + ScriptNode 设置；此外还使用了可观测性工具：get_joint_config、搭配 observe_prims 的 step_simulation、get_physics_state，以及用于脚本热重载的 edit_action_graph。

开发

# Run the MCP inspector
./.venv/bin/python -m mcp dev ./isaac_mcp/server.py

检查器可通过 http://localhost:5173 访问。

设置说明

覆盖默认值：

PYTHON_SPEC=3.11 ./scripts/setup_python_env.sh
ISAACSIM_ROOT=/opt/isaacsim ./scripts/run_isaac_sim.sh
ISAACSIM_ENGINE=newton ./scripts/run_isaac_sim.sh

引擎选择配置位于 scripts/lib/isaac_launcher.sh 中：每种引擎都映射到 Isaac Sim 随附的启动脚本。添加新条目即可支持新的后端，并在每个启动脚本中启用 ISAACSIM_ENGINE=<name> 和 --<name>。

# Make sure you're in the repo root
pwd
test -f ./isaac.sim.mcp_extension/config/extension.toml && echo OK

贡献

欢迎提交拉取请求。改进工具、文档、适配器和测试都很有帮助。

许可证

MIT 许可证。版权所有 (c) 2023-2025 omni-mcp，版权所有 (c) 2026 whats2000。请参阅 LICENSE。