Omniverse MCP

Omniverse MCP

让 AI 助手在 NVIDIA Isaac Sim 和其他 Omniverse Kit 应用中工作：
查看场景、编辑场景、运行物理模拟、操控机器人并记录发生的情况。

_{在 Isaac Sim 6.2 中调用一次 capture_viewport：返回画面以及每个对象各自的颜色，并附上图例和屏幕上的边框，告知助手它看到了什么。}

Omniverse MCP 将 Claude Code、Cursor 或 VS Code 等 AI 客户端连接到正在运行的 Kit 应用。它由同一版本发布的两部分组成：

• 服务端， omniverse-mcp：AI 客户端启动的 MCP 服务，来自 PyPI；
• 桥接扩展， ovmcp.bridge：Kit 应用内的 Kit 扩展，在 Kit 中列为 Omniverse MCP Bridge，并收录在 Kit 的社区扩展注册表中。

Claude Code 用户可通过一个插件获取两者，插件还为每类工作提供了技能。

AI client  --MCP, stdio-->  omniverse-mcp  --HTTP, with a token-->  ovmcp.bridge
                            (the server)                         (inside the Kit app, port 8211)

要求

• **Kit 107 或更高版本的 Kit 应用，**支持 Windows 或 Linux。已在 Isaac Sim 6.2（Windows 和 Linux）以及 5.1 （Linux）上测试；USD Composer 和其他 Kit 应用应该也能运行，但尚未测试。在 Linux 上，Isaac Sim 5.1 可使用 NVIDIA 的 580 驱动运行；使用 595 驱动时，渲染器会在启动时崩溃。
• **uv，**用于运行服务。安装后，打开一个新终端并重启 AI 客户端，以便两者都能找到 uvx：
  • macOS 和 Linux：curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• **能够读取文件的 MCP 客户端：**工具会将图像和较长的回答写入文件，并返回文件路径。
• **Kit 和客户端位于同一台机器上，**否则请参阅在另一台机器上运行 Kit。

安装

Claude Code：插件

在 Claude Code 中：

/plugin marketplace add serionist/omniverse-mcp
/plugin install omniverse-mcp@omniverse-mcp

如果它提示你这样做，请运行 /reload-plugins。在终端中，也可以运行 claude plugin marketplace add serionist/omniverse-mcp，然后运行 claude plugin install omniverse-mcp@omniverse-mcp；插件会在 Claude Code 下次启动时加载。

然后运行 /omniverse-mcp:setup。它会安装插件发行版中的桥接程序，告诉你在 Kit 中需要点击哪些位置，并 检查连接。插件还提供了适用于场景、几何体、仿真、脚本和错误报告的技能，Claude 会在请求适用时使用这些技能（插件）。

其他 MCP 客户端

1. 安装桥接程序：

   uvx omniverse-mcp extension install
   

   它会将 ovmcp.bridge 复制到你的用户数据文件夹，然后打印 Kit 所需的文件夹路径；该路径对应的说明是“Kit 的扩展搜索路径中包含此文件夹后，便能找到它”。你也可以从 Kit 的社区注册表直接在 Kit 中安装桥接程序，并在第 3 步将其版本提供给服务端 （从 Kit 的社区注册表安装）。

2. 在 Kit 应用中将其启用一次：

   1. 依次点击 Window > Extensions、右上角的菜单（☰）和 Settings。
   2. 在 Extension Search Paths 下，点击绿色的 +，然后粘贴文件夹路径。+ 会添加一个空行，点击该行即可输入。
   3. 在 THIRD PARTY 下搜索 ovmcp，然后启用 Omniverse MCP Bridge，并勾选 Autoload。

   桥接程序会立即启动，Kit 的控制台会显示 [ext: ovmcp.bridge-<version>] startup。Kit 会在退出时保存搜索路径和 Autoload 设置，因此请通过 File > Exit 退出一次。无头 Kit 则使用 --ext-folder <that folder> --enable ovmcp.bridge（无头 Kit）。

3. **将服务端添加到客户端的 MCP 配置中，**然后重启客户端。在大多数客户端的 JSON 配置中：

   {
     "mcpServers": {
       "omniverse": { "command": "uvx", "args": ["omniverse-mcp"], "env": { "PYTHONPATH": "" } }
     }
   }
   

   MCP 客户端中列出了各客户端的配置文件和配置格式，包括 VS Code 和 Codex。空的 PYTHONPATH 可确保服务端使用的 Python 路径不受 Isaac Sim 环境设置的影响。

客户端会随附服务端的简短说明。如果它忽略了这些说明，请参阅 docs/AI_GUIDE.md；其中也介绍了如何将插件技能作为纯 Markdown 文件使用。

检查是否正常运行

Kit 应用运行时，请让助手 “调用 get_sim_state”。它会返回类似这样的内容：

state = stopped
up_axis = Z
...
extension_version = 0.5.1
server_version = 0.5.1

遇到其他问题？请参阅故障排除。

**曾在 0.2.0 之前使用过此扩展？**它来自本仓库的克隆版本，而在此之前名为 isaacsim.mcp.bridge。请关闭旧扩展并移除其搜索路径，以确保 Kit 只加载一个副本。请参阅 更新日志。

你可以提出哪些请求

“场景里有什么？捕获视口画面，并告诉我每个对象的位置。”

“在原点放一张桌子，上面放一个红色、一个绿色和一个蓝色的立方体，并调整灯光，让捕获的画面不是黑的。”

“从 /World/Table 的四个顶角查看场景，并隐藏其他所有内容。”

“/World/Robot 有多少个面？哪些部分的面最多？”

“在桌子上添加一条 Franka 机械臂，并列出它的关节及其限位。”

“让一个立方体从一米高处落下，录制它下落的两秒过程，并展示最后一帧。”

“将 /World/Table 导出为独立的 USD 文件。”

“操作失败了。显示 Kit 的警告和错误信息。”

工具

区域	工具	功能
场景	get_scene_tree, get_prim_properties, get_prim_bounds, set_prim_transform, create_prim, delete_prim, clone_prim, set_visibility, set_prim_attribute, save_scene, open_scene, new_scene	读取场景的层级结构和属性；创建、移动、复制、隐藏和删除对象；设置属性，例如灯光的强度；保存、打开文件或启动空场景
相机	capture_viewport, inspect_prim, capture_sweep, set_camera, viewport_light	捕获视口，并显示每个对象的屏幕框和颜色；从多个方向查看单个对象；在一次任务中捕获多个视角和变体状态，并在更改后再次捕获；将相机对准某个点或对象；为视图打光
材质	set_material, update_material_paths	设置对象的颜色和表面；在文件移动后修复材质路径
仿真	sim_control, get_sim_state, get_performance	播放、暂停、停止和逐步运行物理仿真；查看状态、向上轴和版本；测量帧率、物理步长和 GPU 内存
物理	set_physics_properties, apply_force, raycast	设置质量、摩擦力和弹性；创建碰撞体；推动对象；发射射线
机器人	create_robot, get_robot_info, set_joint_targets	从 Isaac Sim 库中添加机器人（Franka、UR10、G1、Spot 等）；读取其关节及位置；设置关节目标
录制	start_recording, stop_recording, get_recording_frame	在物理仿真运行时，以任意尺寸从任意相机录制帧和对象状态，然后查看任意帧
几何体	get_mesh_stats, compare_prims	统计面和顶点数量并找出最复杂的部分；比较两个对象或变体
USD 文件和变体	flatten_usd, export_prim_as_file, create_variant_structure, set_variant_selection	将舞台写入单个文件；导出对象；创建并切换变体集
Kit	get_logs, manage_extensions, draw_debug	读取 Kit 日志；启用和停用 Kit 扩展；在视口中绘制线条和点
脚本	execute_script, run_script_job, get_job, cancel_job	在 Kit 中运行 Python，完成其他工具无法完成的任务；Kit 渲染时将长脚本作为任务运行；查看进度并取消任务

每个工具及其参数都列在工具参考中。

_{inspect_prim(prim_path="/World/Workcell", angles=["top_front_right", "top_back_right", "top_back_left", "top_front_left"], isolate=True)：一次调用即可查看各个侧面，调整取景以适应画面，并隐藏场景的其余部分。}

更新

服务和桥接来自同一版本，因此请一起更新，然后重启 Kit 和客户端。

• **插件：**运行 claude plugin marketplace update omniverse-mcp，然后运行 claude plugin update omniverse-mcp@omniverse-mcp，并重启 Claude Code。然后运行 /omniverse-mcp:setup，它会 安装匹配的桥接。
• 其他客户端：uvx omniverse-mcp@latest extension install 会获取最新服务并安装其桥接。 在 Windows 上，运行中的 Kit 会占用桥接文件夹：请先退出 Kit。若未固定版本，uvx 也可能自行切换到新版本； 此时服务会给出安装匹配桥接的命令。若要固定到某个版本，请参阅 更新。
• **来自 Kit 社区注册表的桥接：**在 Kit 的 Extensions 窗口中更新桥接，并同时更新服务固定的版本。

配置

服务端

omniverse-mcp [--host HOST] [--port PORT] [--output-dir DIR]    the MCP server, over stdio
omniverse-mcp extension install                                 install the bridge of this release
omniverse-mcp extension path                                    print the folder Kit's search paths need

变量	标志	默认值	说明
OMNIVERSE_MCP_HOST	--host	127.0.0.1	桥接服务的监听地址
OMNIVERSE_MCP_PORT	--port	8211	桥接服务的端口
OMNIVERSE_MCP_OUTPUT_DIR	--output-dir	工作文件夹中的 mcp_output	图片和长答案的保存位置
OMNIVERSE_MCP_TOKEN		令牌文件	桥接服务令牌，用于在另一台机器上运行的 Kit 应用
OMNIVERSE_MCP_STATE_DIR		依系统而定	令牌文件所在文件夹，两端应设置为相同值

插件的服务端会从 Claude Code 启动时所处的环境中读取这些变量。将 mcp_output/ 添加到项目的 .gitignore 中。

桥接服务

设置项	默认值	说明
/exts/ovmcp.bridge/host	127.0.0.1	监听地址
/exts/ovmcp.bridge/port	8211	端口
/exts/ovmcp.bridge/token	为空：每次启动时生成新令牌	固定令牌，用于远程 MCP 服务

在 Kit 的命令行中设置这些参数，例如 --/exts/ovmcp.bridge/port=8212，并在 OMNIVERSE_MCP_PORT 中为服务端指定相同的端口。不要编辑已安装扩展的 extension.toml：下次执行 extension install 时会将其替换。

桥接令牌

桥接服务会运行服务端发送的任意 Python 代码，因此只会响应持有其令牌的服务端。每次启动时，它都会将新令牌写入一个只有你的用户才能读取的文件中，同一台机器上的服务端会读取该文件：无需进行任何设置。来自网页的请求会被拒绝。在另一台机器上运行 Kit 介绍了如何手动设置令牌，架构介绍了该文件的位置。

用于脚本的 Context7

模型没有接受过 Omniverse 和 Isaac Sim API 的训练，因此会猜测它们的名称。将 Context7 作为第二个 MCP 服务后，助手会在编写 execute_script 代码前查询 API（库 isaac-sim/isaacsim）；服务端说明和 script 技能也会要求它这样做。

故障排除

“缺少或错误的桥接令牌”：Kit 以其他用户身份运行、在容器中运行，或在另一台机器上运行。请手动设置令牌（在另一台机器上运行 Kit）。

“Kit 扩展版本低于此 MCP 服务”，或“使用桥接协议”：服务和桥接来自不同版本。运行消息中指定的命令，然后重启 Kit。

“Kit 应用连接失败”、连接被拒绝或超时：Kit 应用是否正在运行，且桥接是否已启用？其控制台会显示 [ext: ovmcp.bridge-<version>] startup。除非 OMNIVERSE_MCP_PORT 指定了其他端口，否则服务会在 8211 端口上查找。首次启动时，Isaac Sim 会编译着色器，耗时数分钟；在此之前，响应会很慢。

“Kit 在……处停止响应”：调用在 120 秒内未收到响应，/health 在 5 秒内也没有响应。Kit 可能正忙于运行一个不会等待的长脚本，或已卡住：Kit 110（Isaac Sim 6.2）在设置新的摄像机视图时，可能会卡死在 NVIDIA 渲染器内部（已知问题中有 NVIDIA 提供的解决方法）。Kit 保持无响应期间，后续调用会在 5 秒后失败；待其恢复响应后，调用即可继续。如果数分钟后仍无响应，请重启 Kit 应用。

Kit 日志显示 [MCP Bridge] Failed to start server：另一个程序或第二个 Kit 应用占用了 8211 端口。为此 Kit 应用指定其他端口，并为服务指定相同的端口（桥接）。

服务无法启动：Claude Code 的 /mcp 会显示错误；其他客户端也有 MCP 日志。客户端启动时的 PATH 中是否包含 uvx？安装 uv 后，请重启客户端。

捕获结果为黑屏，或其中的 prim 变黑：响应会根据光照模式给出警告。viewport_light(action="set", mode="Default") 会照亮视图；mode="camera" 则会设置跟随摄像机的灯光；Kit 应用默认没有灯光。

工具返回错误：get_logs(min_level="warn") 会显示 Kit 报告的内容。get_robot_info 会在物理模拟运行或暂停时读取关节位置；raycast 需要物理模拟至少运行过一次；机器人工具需要 Isaac Sim。

更多信息请参阅 SETUP.md。

已知问题

• **Isaac Sim 6.2（Kit 110）在设置新相机视图时，可能会在 NVIDIA 的渲染器中永久卡住，**此后日志不再更新，工具会报错“Kit at ... stopped answering” (#114)。桥接程序会在两次采集之间保留一个渲染视图，并以该视图的尺寸进行录制，因此只需设置少量新视图，但长时间运行仍可能遇到此问题。NVIDIA 的解决方法是在 Kit 的命令行中添加标志 --/rtx/hydra/supportMultiTickRate=false （isaac-sim/IsaacSim#920；了解如何在 Kit 窗口启动时或无窗口启动时添加该标志：无头 Kit）：NVIDIA 的复现测试使用该标志连续创建 1,000 个新视图两次，而不使用该标志时，在创建 600 个后卡住。代价是：对同一视图进行重复采集时，画面差异会稍大一些。在我们的测试中，时间轴停止时，对 Replicator 中行走的 Agent 进行两次采集，使用该标志时各通道的平均差异约为 3.2/255，不使用时约为 1.2/255。NVIDIA 尚未说明该标志对以不同速率渲染的传感器有何影响。Kit 的渲染器只会在启动时读取该标志：在 Kit 运行期间通过脚本设置它不会重新配置渲染器，还会误导 Replicator 的 step()，因为后者会在每次调用时读取该标志 (#189)。
• **Isaac Sim 6.2（Kit 110.4）在长时间更改场景后，可能会停止响应，**主线程会卡在 Fabric 的填充代码（usdrt.population.plugin）中，桥接程序的代码则完全没有运行：这一问题出现在一项会打开多个场景、运行带碰撞体的物理模拟并进行分割采集的测试顺序中，短时间运行时从未出现。请重启 Kit；桥接程序无法避免此问题 (#162)。上文提到的、用于解决新视图卡死问题的 NVIDIA 标志，在该测试顺序中也避免了此问题：使用标志时，2 次运行各通过 2 次；不使用时，Kit 9 次中卡住 9 次。

如遇到其他问题，请提交问题。工具行为异常时，助手会询问你是否要报告，然后根据版本、调用信息和 Kit 日志起草报告；你确认草稿后，它会通过 GitHub CLI 提交报告，否则会留给你自行发布（插件的 report-bug 技能）。

安全

此桥接程序会按设计执行服务端发送的任意 Python 代码：execute_script 和 run_script_job 都是工具。令牌可以阻止其他程序和网页访问，但无法阻止你自己的 AI 客户端，因此请设置为在执行 execute_script、run_script_job 和 manage_extensions 前先征求确认。 请按照 SECURITY.md 中的说明私下报告漏洞。

文档

• 详细设置说明：各客户端的配置、无头 Kit、端口、远程设置、卸载
• 工具参考：所有工具、参数和提示
• 插件：Claude Code 插件提供的功能及其技能
• 不使用插件：其他客户端的上下文和工作流
• 架构：服务端和桥接程序的工作方式，供贡献者参考
• 更新日志、安全、贡献指南

在 1.0 版本发布前，小版本更新可能会更改工具；更新日志会在“Breaking”部分列出此类更改。如有问题、想法或错误，请提交问题。

许可证

MIT。与 NVIDIA 无关联，也未获 NVIDIA 认可；Omniverse 和 Isaac Sim 是 NVIDIA 的商标。