内容
# NVIDIA Omniverse MCP 服务器
通过 [模型上下文协议](https://modelcontextprotocol.io) 实现 **NVIDIA Omniverse** 和 **Isaac Sim** 的 AI 驱动控制。借助 Claude Code、Codex 或任何与 MCP 兼容的 AI 代理，从自然语言构建整个 3D 世界、数字孪生、物理模拟和动画。
## 架构
```
┌─────────────────────┐ MCP/stdio ┌──────────────────────┐
│ Claude Code / Codex │ ◄──────────────────► │ MCP 服务器 │
│ （AI 代理） │ │ （Python，uv） │
└─────────────────────┘ └──────────┬───────────┘
│ WebSocket
│ localhost:8766
┌──────────▼───────────┐
│ Kit 扩展 │
│ （在 Omniverse / │
│ Isaac Sim 进程内） │
└──────────────────────┘
```
MCP 服务器在终端中运行，并通过 stdio 与 AI 代理通信。它通过 WebSocket 将命令转发给在 Omniverse 中运行的 Kit 扩展，该扩展在实时舞台上执行 USD/PhysX 操作。
## 快速入门
### 1. 安装 MCP 服务器
```bash
cd omniverse-mcp
uv sync
```
### 2. 安装 Kit 扩展
将 `kit_extension/` 目录复制或符号链接到您的 Omniverse 扩展文件夹中：
**选项 A — 符号链接：**
```bash
# Isaac Sim
mklink /D "C:\Users\<you>\isaacsim\IsaacSim\source\extensions\omni.mcp_extension" "C:\path\to\omniverse-mcp\kit_extension"
# 或在启动时使用直接扩展路径：
isaac-sim --ext-path /path/to/omniverse-mcp/kit_extension --enable kit_extension
```
**选项 B — 扩展管理器：**
1. 打开 Omniverse / Isaac Sim
2. 在名为 `omni.mcp_extension` 的父文件夹下创建一个包含扩展的文件夹。
3. 示例：使 `C:\Users\<you>\omniverse-exts\omni.mcp_extension` 指向此存储库的 `kit_extension`
4. 窗口 > 扩展
5. 点击齿轮图标，添加父文件夹，例如 `C:\Users\<you>\omniverse-exts` 到搜索路径
6. 重新同步注册表，然后搜索 `omni.mcp_extension` 或 `Omniverse MCP 扩展` 并启用它
重要：
- 不要将 `kit_extension/` 本身作为扩展管理器搜索文件夹。搜索文件夹会扫描包含 `extension.toml` 的子文件夹。此存储库的 `kit_extension/` 已经是扩展根目录，因此应使用 `--ext-path` 或放置在父文件夹下作为 `omni.mcp_extension/`。
- `--ext-path` 使扩展可发现，但扩展仍需要启用。
- 如果您直接传递存储库的 `kit_extension/` 目录与 `--ext-path`，扩展名为 `kit_extension`，因为 Kit 从文件夹名称派生扩展 ID。
- 如果您将其放在父文件夹下作为 `omni.mcp_extension/`，然后启用 `omni.mcp_extension`。
### 3. 配置 Claude Code
将以下内容添加到您的项目的 `.mcp.json` 中（已包含在此存储库中）：
```json
{
"mcpServers": {
"omniverse": {
"command": "/path/to/omniverse-mcp/scripts/run_omniverse_mcp.sh",
"args": [],
"env": {
"UV_PROJECT_ENVIRONMENT": "${UV_PROJECT_ENVIRONMENT:-}",
"OMNIVERSE_WS_HOST": "${OMNIVERSE_WS_HOST:-}",
"OMNIVERSE_WS_PORT": "${OMNIVERSE_WS_PORT:-8766}"
}
}
}
}
```
或直接从 CLI 添加：
```bash
claude mcp add omniverse --scope project \
--env OMNIVERSE_WS_PORT=8766 \
-- /path/to/omniverse-mcp/scripts/run_omniverse_mcp.sh
```
启动器在从 WSL 运行时的 Windows 主机 IP 地址时自动检测。如果需要，您仍然可以显式覆盖任一变量：
```bash
export OMNIVERSE_WS_HOST=10.255.255.254
export OMNIVERSE_MCP_COMMAND=/path/to/omniverse-mcp/.venv/bin/omniverse-mcp
```
### 4. 开始使用
1. 启动 Omniverse / Isaac Sim（Kit 扩展自动启动）
2. 在此项目目录中打开 Claude Code
3. 请求 Claude 创建内容：
> “创建一个 80m x 40m 的仓库，带有 4 个货架通道。添加工业照明和混凝土地板。”
## 故障排除 Claude Code
如果 `/mcp` 显示 **Disconnected**，通常是 Claude Code 无法启动本地 MCP 进程。在此项目中，最可靠的解决方法是启动存储库的包装脚本而不是 `uv run`。
检查清单：
- 在此存储库中运行 `uv sync` 以确保 `.venv/bin/omniverse-mcp` 存在。
- 优先使用 `/path/to/omniverse-mcp/scripts/run_omniverse_mcp.sh` 作为 MCP 命令。
- 对于用户范围或手动添加的服务器，使用绝对路径而不是 `.`，以便在存储库根目录之外工作。
- 如果您在 WSL2 上使用 Isaac Sim 在 Windows 上运行，请在 `localhost` 留空或将其设置为 Windows 主机 IP 地址，而不是 `localhost`。
- 启动器可以使用 `OMNIVERSE_MCP_COMMAND` 覆盖可执行文件路径。
- 如果 `uv sync` 失败，报错 `failed to remove file ... .venv\\lib64: Access is denied`，则存储库 `.venv` 通常不完整。在这种情况下，请删除损坏的 `.venv` 并在 Linux 文件系统上重新创建环境：
```bash
UV_PROJECT_ENVIRONMENT=/tmp/omniverse-mcp-venv uv sync
export OMNIVERSE_MCP_COMMAND=/tmp/omniverse-mcp-venv/bin/omniverse-mcp
```
- 您也可以在启动 Claude Code 之前导出 `UV_PROJECT_ENVIRONMENT`；包含的 `.mcp.json` 和启动器现在会自动传递它。
- 验证服务器命令本身是否启动：`timeout 5 /path/to/omniverse-mcp/scripts/run_omniverse_mcp.sh`
- 使用 `claude mcp get omniverse` 检查保存的 Claude 配置
### WSL2 到 Windows
如果 Claude Code 在 WSL2 中运行但 Isaac Sim 在 Windows 上运行：
- 在最近的 WSL 中镜像网络模式下，优先使用 `localhost`。
- 在默认的 WSL2 NAT 模式下，连接到 Windows 主机 IP 地址而不是 `localhost`。
- `/etc/resolv.conf` 中的第一个 `nameserver` 条目仅是一个备用启发式方法，可能是一个 DNS 端点而不是正确的 Windows 主机地址。
包含的启动器脚本自动处理常见的 WSL 情况。它首先探测 `localhost`，如果无法访问环回地址，则回退到 Windows 端地址启发式方法。存储库中的 Kit 扩展默认监听 `0.0.0.0:8766`，因此只要选择正确的主机并允许 Windows 防火墙连接，WSL 就可以从中访问。
重要：Claude Code 显示 MCP 服务器已连接与 Omniverse 连接性是分开的。MCP 服务器可以在 `/mcp` 中连接，而工具调用仍然失败，直到 Omniverse / Isaac Sim 扩展程序在配置的主机和端口上运行并可访问。
### Isaac Sim Python 依赖项
Kit 扩展依赖于 Isaac Sim 捆绑的 Python 环境中的 Python `websockets` 包。扩展程序清单现在通过 `omni.kit.pipapi` 声明该依赖项，因此在具有 Internet 访问权限的机器上，Isaac Sim 应该在启用扩展程序之前自动安装它。
如果自动安装失败，请在 Windows 上从 Isaac Sim 根目录手动安装：
```bat
python.bat -m pip install websockets==16.0
```
然后使用启用扩展重新启动 Isaac Sim。
## 工具（60+）
### 连接和场景信息
- `get_scene_info` — **始终首先调用。** 验证连接性，返回阶段信息。
- `get_stage_hierarchy` — USD 舞台的嵌套树视图。
### 场景管理
- `new_stage` — 创建一个全新的舞台，带有可选模板（空，地面平面，室内，室外）。
- `open_stage` / `save_stage` — 打开/保存 USD 文件。
- `add_reference` / `create_layer` — USD 组合。
### 原始创建和操作
- `create_prim` — 创建立方体，球体，圆柱体，圆锥，胶囊，平面，网格，Xform，范围。
- `create_mesh` — 具有显式顶点/面的程序几何。
- `modify_prim` / `delete_prim` / `duplicate_prim` — CRUD 操作。
- `group_prims` / `create_grid` — 组织和实例化。
### 变换
- `set_transform` / `get_transform` / `move_prim` — 位置，旋转，缩放。
- `align_prims` / `distribute_prims` — 多原始对齐和分布。
### 材料和着色器
- `create_material` — OmniPBR，OmniGlass，UsdPreviewSurface，带有颜色，粗糙度，金属，纹理。
- `assign_material` / `modify_material` — 绑定和编辑材料。
### 照明和环境
- `create_light` — 远光，穹顶光，球体光，矩形光，圆盘光，圆柱光。
- `set_environment` — HDRI 天空穹顶。
- `create_sky` — 一键创建逼真室外照明（早晨，中午，日落，夜晚）。
### 相机和视口
- `create_camera` — 具有观察目标的透视/正交。
- `set_active_camera` / `capture_viewport` — 视口控制和截图。
### 物理和碰撞
- `create_physics_scene` — PhysX 场景，带有重力，解算器，CCD，GPU 动力学。
- `add_rigid_body` / `add_collider` / `add_ground_plane` — 物理设置。
- `create_joint` — 固定，旋转，棱柱，球面，距离关节。
- `add_force_field` — 风，阻力，噪声力场。
- `overlap_test` / `raycast` — 物理查询。
### 动画和时间线
- `set_keyframe` / `create_animation_clip` — 关键帧动画。
- `set_timeline` / `play_animation` / `stop_animation` — 时间线控制。
- `create_skeletal_animation` — 将动画剪辑应用于绑定角色。
### 人物
- `spawn_character` — 放置绑定的人物。
- `set_character_animation` — 空闲，行走，奔跑，坐下，挥手，讲话。
- `create_crowd` — 在区域内分散动画人物。
- `create_character_path` — 定义航点导航路径。
### 数字孪生模板
- `create_warehouse` — 完整的仓库，带有货架，通道，照明，码头。
- `create_solar_farm` — 面板阵列，带有逆变器，变电站，地面。
- `create_wind_farm` — 带有动画转子的涡轮机，通道。
- `create_factory_floor` — 工作站，输送带，安全区。
- `create_data_center` — 服务器机架，热/冷通道，冷却。
### 模拟控制
- `start_simulation` / `stop_simulation` / `step_simulation` — 物理播放。
- `get_simulation_state` / `set_simulation_speed` — 监控和速度控制。
### 资产管理
- `list_assets` / `import_asset` — 浏览和导入 USD，FBX，OBJ，glTF，STL 文件。
- `search_nvidia_assets` — 搜索 NVIDIA Omniverse 资产库。
### 场景查询
- `get_prim_info` / `find_prims` — 检查和搜索阶段。
- `get_bounding_box` / `measure_distance` — 空间查询。
### 渲染
- `set_render_mode` — RTX Realtime，Interactive，Accurate，Iray。
- `set_render_settings` / `render_to_file` — 生产质量的渲染。
### 代码执行（紧急出口）
- `execute_python` — 在 Kit 进程中运行任意 Python，完全访问 `omni.*` 和 `pxr`。
- `execute_python_file` — 执行 `.py` 脚本文件。
## 配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `OMNIVERSE_WS_HOST` | `localhost` | Kit 扩展的 WebSocket 主机 |
| `OMNIVERSE_WS_PORT` | `8766` | WebSocket 端口 |
Kit 扩展从 extension.toml 或 carb 设置中读取其设置：
- `/exts/omni.mcp_extension/ws_host` — 服务器绑定地址
- `/exts/omni.mcp_extension/ws_port` — 服务器端口
## 开发
### 测试
```bash
# 运行单元测试（无需 Omniverse）
uv run pytest tests/ -v
# 交互式 MCP 调试
uv run mcp dev mcp_server/server.py
```
### 项目结构
```
omniverse-mcp/
├── mcp_server/ # MCP 服务器（在终端运行）
│ ├── server.py # 入口点
│ ├── ws_client.py # WebSocket 客户端
│ └── tools/ # 16 个工具模块
├── kit_extension/ # Omniverse Kit 扩展
│ ├── config/ # extension.toml
│ └── omni/mcp_extension/
│ ├── extension.py # on_startup / on_shutdown
│ ├── ws_server.py # WebSocket 服务器
│ ├── command_router.py
│ └── handlers/ # 16 个命令处理程序
├── tests/
└── examples/ # 示例提示
```
## 许可证
MIT
故障排除：
cd /mnt/c/Users/mstef/omniverse/omni_isaacsim_mcp
unset OMNIVERSE_MCP_COMMAND
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/omniverse-mcp"
rm -rf "$UV_PROJECT_ENVIRONMENT"
uv venv "$UV_PROJECT_ENVIRONMENT"
ls -l "$UV_PROJECT_ENVIRONMENT/bin/python"
timeout 5 ./scripts/run_omniverse_mcp.sh
期望结果：
然后从同一个 shell 启动 claude，并运行：
claude mcp remove omniverse -s user
claude mcp reset-project-choices
claude mcp get omniverse
