IsaacSim-MCP
Controls NVIDIA Isaac Sim through named, verifiable MCP tools, covering USD scene creation and manipulation, robots/articulations, joint drives and motion planning, sensors and RTX camera capture, PhysX physics setup, Action Graph and ScriptNode management, Replicator synthetic data generation jobs, animated human characters, NVIDIA asset libraries, and simulation playback control.
Manages ROS 2 publishers on the Isaac Sim stage via Action Graphs, allowing simulated sensor and robot data to be published to ROS 2 topics.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
IsaacSim-MCP
通过 MCP,让 AI 客户端控制 NVIDIA Isaac Sim 的场景、机器人、传感器与仿真工作流。
当前版本:0.7.0 · 主要维护环境:Windows / Isaac Sim 6.2
快速开始 · 功能概览 · 客户端配置 · 最新验收报告 · 文档目录
验收状态
2026-11-12,在 Isaac Sim 6.2.0-rc.14 / Windows / PhysX 隔离宿主中完成约定范围验收:
706 项离线测试通过,0 失败;53 项按实时宿主或 Unix 启动器标记排除。
legacy模式 136 / 138 个工具已有成功实机覆盖;full模式 158 / 160 个工具名已有成功实机覆盖。USD Search、Beaver3D 未调用、未验收,不计入通过项。
已修复并复测机器人混合 GPU 场景、Kaya 控制、人物 schema、MPM 任务桥接,以及 ROS 相机和雷达停止后无法重播的问题。
MPM 和保存插件仅作为外部提供者参与隔离测试,未修改其源码或正式项目资产。
“实机覆盖”包含原生 MCP 调用,以及扩展命令执行、操作后读回与离线路由契约的组合证据;不代表所有参数组合或其他版本都已验证。具体范围见验收报告和逐项结果。
Related MCP server: omni-kit-mcp
目录
功能概览
领域 | 能力 |
USD 场景 | 创建、查询、变换、组合、引用、语义标注、类型化属性、多层批处理、保存与受控撤销 |
机器人 | 关节状态与驱动、运动规划、夹爪、移动底盘;处理场景或机器人替换后的运行时重建 |
相机与雷达 | RGB、深度、分割等相机输出,RTX LiDAR 点云;原生 MCP 图片和大型数据传输 |
物理与材质 | PhysX 场景、刚体、碰撞体、碰撞组、关节、PBR 材质和物理材质 |
图与 ROS 2 | Action Graph、ScriptNode,以及 Clock、TF、JointState、相机和雷达发布器 |
合成数据与人物 | Replicator SDG 任务、NavMesh、人物生成、移动、注视、空闲及行为控制 |
可选 MPM 桥接 | 配置发现与对比、Session 参数修改、版本校验、异步构建与任务状态 |
可选源文件保存桥接 | 预览并提交选定的 Session 默认值到一个源文件,保留无关覆盖 |
诊断与治理 | 命令 ID、幂等控制、任务取消、操作后读回、回滚、脱敏日志和崩溃恢复状态 |
本仓库只维护 MCP。 MPM 求解器和保存插件是独立项目,不随本仓库安装,也不会被工具自动安装或启用。缺少提供者时返回明确错误,不影响其他领域。
工具清单由源码自动生成;实际可用工具以当前 tools/list 和 get_capabilities 为准。
架构
AI 客户端 → Python MCP 服务 → TCP → Isaac Sim 扩展 → 处理器 → 适配器 → Isaac Simflowchart LR
A[AI / MCP 客户端] -->|stdio 或 Streamable HTTP| B[Python MCP 服务]
B -->|本地 TCP| C[Isaac Sim 扩展]
C --> D[命令处理器]
D --> E[V5 / V6 适配器]
E --> F[Isaac Sim / USD / PhysX]MCP 服务与 Isaac Sim 是独立进程:客户端启动 MCP 服务,Isaac Sim 内的扩展执行场景操作。详细分工见 ARCHITECTURE.md。
快速开始
准备完整的 Isaac Sim 6.2 安装,以及 Python 3.10 或更新版本。MCP 服务使用独立 Python 环境;扩展使用 Isaac Sim 自带环境。
1. 安装 MCP 服务
git clone https://github.com/ykykykk/IsaacSim-MCP.git
cd IsaacSim-MCP
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .2. 配置本机路径与端口
Copy-Item config.example.json config.local.json编辑 config.local.json,例如:
{
"isaac_root": "F:/isaac-sim/6.2.0",
"host": "127.0.0.1",
"port": 8766,
"tool_profile": "legacy",
"tool_domains": "all"
}安装路径是示例,请按本机实际位置填写。端口必须与 Isaac Sim 扩展一致;已有配置使用其他端口时,不必改回 8766。config.local.json 不提交 Git。
配置优先级:显式启动参数 > 环境变量 > 配置文件 > 通用默认值。可用 ISAAC_MCP_CONFIG 指定另一个配置文件;.env.example 仅供参考,不会自动加载。
3. 启动 Isaac Sim
.\scripts\run_isaac_sim.ps1启动器根据配置加载本仓库扩展,并显式传递连接端口。需要进程监督与异常恢复时,改用:
.\scripts\run_isaac_sim_supervised.ps14. 连接客户端
按下一节配置 MCP 客户端。连接后先调用 get_capabilities,再调用 get_scene_info,确认宿主版本、扩展来源及当前场景,再执行修改。
详细安装说明见 Windows 安装指南;6.2 配置及工作流契约见 6.2 工作流指南。历史验收结论以本页链接的最新报告为准。
客户端配置
默认使用 stdio,不需要 HTTP 或公网入口。支持 mcpServers 格式的客户端可参考:
{
"mcpServers": {
"isaac-sim-live": {
"command": "F:\\Resources\\Projects\\Software\\IsaacSim-MCP\\.venv\\Scripts\\python.exe",
"args": ["-m", "isaac_mcp.server"],
"env": {
"ISAAC_MCP_HOST": "127.0.0.1",
"ISAAC_MCP_PORT": "8766"
}
}
}
}将 command 改为仓库虚拟环境的绝对路径,端口与宿主保持一致。不同客户端的配置文件格式可能不同,但启动命令和参数相同。
环境变量 | 默认值 | 用途 |
| 由本机配置指定 | Isaac Sim 安装目录 |
| 仓库 | 配置文件路径 |
|
| Isaac Sim 扩展的 TCP 地址 |
|
| Isaac Sim 扩展的 TCP 端口 |
|
| 工具名称与接口模式 |
|
| 工具领域过滤 |
|
| MCP 传输方式 |
工具模式与领域过滤
工具模式控制名称和接口:
legacy:默认模式,保留既有工具名称和参数契约。consolidated:使用action、publisher_type等参数合并同类操作,减少客户端工具数量。full:同时暴露两套名称,供迁移和测试使用,不建议长期使用。
领域过滤独立于工具模式:
领域 | 内容 |
| 诊断、任务、产物与仿真控制;始终保留 |
| USD、物体、材质、灯光、资产、图与保存 |
| 物理配置与构建 |
| 机器人、控制器、运动、传感器与 ROS 2 |
| 可选 MPM 桥接 |
| Replicator 与人物 |
例如只开放场景和物理相关工具:
$env:ISAAC_MCP_TOOL_PROFILE = "consolidated"
$env:ISAAC_MCP_TOOL_DOMAINS = "core,scene,physics"修改后重新启动 MCP 服务,并让客户端重新获取工具列表。完整名称对照见工具模式说明。
启动与故障恢复
监督启动器沿用本机路径、扩展、端口及物理 GPU 选择策略。默认在 300 秒窗口内最多重启 3 次,采用递增等待;退出码为 0 时视为正常关闭,不自动重开。若已存在健康宿主,或端口被无响应进程占用,会拒绝重复启动。
MCP 服务仍由客户端独立启动。get_runtime_status 可在 Isaac Sim 不可连接时读取最后已知退出状态、重启次数及脱敏日志摘要:
ISAAC_RUNTIME_RECOVERING:正在恢复,等待后再查询。ISAAC_RUNTIME_CRASHED:已崩溃,先检查原因。ISAAC_RUNTIME_UNAVAILABLE:宿主不可用,检查启动器与配置。
断线后不自动重放写操作。 恢复连接后先读回状态,确认前一次操作是否生效,再决定下一步。
状态文件默认位于 %LOCALAPPDATA%\IsaacSim-MCP\6.2\runtime-<port>.json。可通过 ISAAC_MCP_RUNTIME_STATE_FILE 和 ISAAC_MCP_RUNTIME_LOG_FILE 指定状态文件及 Kit 日志位置。详情见运行监督与崩溃恢复。
HTTP 与远程访问
本地 stdio 是默认方案。确需 Streamable HTTP 时,在单独的 PowerShell 中启动:
$env:ISAAC_MCP_TRANSPORT = "streamable-http"
$env:ISAAC_MCP_HTTP_HOST = "127.0.0.1"
$env:ISAAC_MCP_HTTP_PORT = "8000"
$env:ISAAC_MCP_TOOL_PROFILE = "consolidated"
$env:MCP_ALLOWED_HOSTS = "localhost,127.0.0.1"
.\.venv\Scripts\python.exe -m isaac_mcp.serverMCP 地址为 http://127.0.0.1:8000/mcp。HTTP 的 8000 端口与扩展 TCP 的 8766 端口用途不同,不能混用。
现有 HTTP 服务没有身份认证。Host 校验不等于认证,不要直接公开端口或通过无认证隧道暴露控制接口。 远程部署需要独立配置认证、授权及访问审计,本仓库不自动部署公网服务。
支持范围
组件 | 当前状态 |
Isaac Sim 6.2 / Windows | 当前维护目标;最新实机验收构建为 6.2.0-rc.14 |
PhysX | 当前实机验收后端 |
Isaac Sim 6.0.1 / Windows | 保留上游历史验证记录,不与 6.2 证据混用 |
Isaac Sim 5.1.x | 保留旧版适配器,不在本轮验收范围 |
Newton | 仅使用当前能力矩阵明确支持的功能;未纳入本轮 PhysX 验收 |
MPM / 保存插件 | 可选外部提供者;本轮验证 MCP 桥接,不代表生产规模性能或求解精度验收 |
USD Search / Beaver3D | 可选外部服务;本轮未调用、未验收 |
Isaac Lab MCP | 独立范围,尚未纳入本项目 |
软件包、扩展、响应格式和能力矩阵使用独立版本规则,见协议版本与迁移。
安全与操作边界
isaac-sim-live才是实时场景控制通道;文档查询不能证明场景已经改变。写入须满足时间轴、后端、扩展、对象归属及路径条件;破坏性验收仅限明确指定的临时场景。
工具出现在列表中不等于功能通过;验收需要执行结果、操作后读回及清理证据。
优先使用具名工具。
execute_script/reload_script只应执行可信代码,并受执行策略限制。参数修改、构建、播放、内存提交与磁盘保存是不同操作,不互相隐式触发。
API 密钥不应写入源码、聊天中的 MCP 参数、报告或 Git 提交。
本仓库不接管其他插件源码,不自动修改用户正式场景。
常见问题
无法连接 Isaac Sim
确认宿主已启动、扩展已加载,且客户端和宿主使用相同 TCP 地址与端口。调用 get_runtime_status 查看退出或恢复状态。不要把 ISAAC_MCP_PORT 填成 HTTP 服务端口。
若崩溃报告程序尚未退出,可能暂时没有退出码;运行时诊断仍可提供最新 Kit 日志的有限摘要。完整日志保留在本机。
工具显示正常,调用却返回 Unknown tool
客户端缓存的工具列表可能与当前模式不一致。确认 ISAAC_MCP_TOOL_PROFILE 和 ISAAC_MCP_TOOL_DOMAINS,重启服务并重新连接客户端。
例如 legacy 使用 play_simulation、open_gripper,consolidated 使用 control_timeline、control_gripper。迁移期间可临时使用 full,完成后切回所需模式。
相机成功返回,但客户端没有显示图片
使用 RGB capture_camera_output(..., output_type="rgb", return_mode="image") 或 capture_image(..., return_mode="image")。artifact 返回受管理的数据句柄,inline 返回 JSON 中的 base64,均不等同于原生 MCP ImageContent。
若响应已有 ImageContent,但界面仍不显示,需检查客户端是否支持图片内容。若收到 CAMERA_FRAME_NOT_READY,先检查相机、时间轴与渲染状态,不在单次请求中无限重试。
机器人替换后出现无效物理张量或 IK 错误
当前实现会在场景或机器人身份变化后丢弃旧绑定,并重建失效的物理运行时。若仍报错,确认 MCP 服务与扩展来自同一版本,重新启动 Isaac Sim 后读回关节配置。不要用反复播放、暂停或盲目重发写命令代替诊断。
ROS 2 发布器或可选插件不可用
先查询 get_ros2_status 或 get_capabilities。ROS 2 需要启用 bridge、core、nodes 扩展;MPM 和源保存需要各自外部提供者。工具不会替用户自动启用插件。
HTTP 返回 421 Misdirected Request
请求的 Host 不在允许列表中。MCP_ALLOWED_HOSTS 接受逗号分隔的精确主机名,不接受 *.example.com 这类通配符。调整 Host 列表不会为服务增加身份认证。
开发与文档
开发依赖使用 uv sync --dev 安装。需要主动运行离线检查时:
$env:PYTHONUTF8 = "1"
$env:ISAAC_MCP_TOOL_DOMAINS = "all"
$env:ISAAC_MCP_TOOL_PROFILE = "legacy"
uv run pytest -q -m "not live and not unix_launcher"
uv run ruff check .以上为 Windows 离线验收命令。实机测试需另行显式启用,并使用隔离场景测试框架;禁止把历史破坏性测试指向正在编辑的用户场景。
常用文档:
许可证与来源
本项目基于 Tim0320/IsaacSim-MCP,延续 whats2000/isaacsim-mcp-server 的工作,使用 MIT 许可证。分发修改版时请保留许可证、版权声明与上游归属。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables natural language control of NVIDIA Isaac Sim through the Model Context Protocol, allowing you to create robots, build scenes, run simulations, and debug physics from any MCP-compatible IDE.4258 PyPI70MIT
- AlicenseAqualityCmaintenanceEnables driving Omniverse Kit apps (Isaac Sim, Isaac Lab) over MCP, allowing agents to control simulations, run Python, and call namespace-scoped tools via a single bridge.13Apache 2.0
- AlicenseCqualityCmaintenanceEnables AI assistants to control NVIDIA Isaac Sim by building scenes, loading assets, operating robots and humans, reading sensors, managing simulation, and creating Action Graphs.1291MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to discover and invoke versioned external tools through an MCP or REST gateway with authentication, authorization, mutation safety, reliability controls, audit logging, and replay.Apache 2.0