IsaacSim-MCP

用 Model Context Protocol（MCP）控制 NVIDIA Isaac Sim。AI 助理可以建立工廠場景、載入 NVIDIA 資產、操作機器人與人物、讀取感測器、控制模擬，以及建立 Action Graph。

此版本以 Windows 與 Isaac Sim 6.0.1 為主要驗證環境，包含 45 個 MCP tools、NVIDIA Replicator Agent 人物支援、NVIDIA 資產目錄，以及工廠配置與互動範例。

本專案延伸自 whats2000/isaacsim-mcp-server，沿用 MIT License。原始作者與後續貢獻者資訊保留於 LICENSE 及原始檔案標頭。

功能

• 建立、查詢與清除 USD 場景
• 建立基本物件、燈光、PBR 材質與 physics material
• 載入 USD、匯入 URDF、搜尋及生成 3D 資產
• 建立機器人並讀寫 articulation joint
• 產生 NVIDIA IRA 動畫人物，支援 wander、patrol、stop、manual
• 建立 Camera 與 RTX LiDAR，輸出 RGB 影像及點雲
• 播放、暫停、停止及逐 frame 執行模擬
• 建立 Action Graph、ScriptNode、連線與 attribute
• 執行或重新載入 Isaac Sim Python script
• 建立 10 個工作區、3 台 AGV、機器手臂、輸送帶與人物的工廠範例

系統需求

項目	需求
作業系統	Windows 10／11 64-bit
Isaac Sim	6.0.1，預設安裝位置為 C:\isaacsim
Python	3.10 以上
MCP 套件	mcp[cli]>=1.28.1,<2
網路連接埠	TCP 8766

Isaac Sim 與 MCP Server 是兩個獨立程序：

AI 助理 / MCP Client
        │ stdio
        ▼
Python MCP Server
        │ TCP 127.0.0.1:8766
        ▼
Isaac Sim MCP Extension
        │
        ▼
Isaac Sim 6.0.1 / USD / PhysX

安裝

1. 下載專案

git clone https://github.com/Tim0320/IsaacSim-MCP.git
cd IsaacSim-MCP

2. 建立 Python 環境

使用 Python 內建工具：

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e .

或使用 uv：

uv sync

3. 指定 Isaac Sim 位置

若 Isaac Sim 位於 C:\isaacsim，可直接略過這一步。其他位置請在目前 PowerShell session 設定：

$env:ISAACSIM_ROOT = "D:\你的\IsaacSim\路徑"

啟動

1. 啟動 Isaac Sim 與 Extension

在第一個 PowerShell 視窗執行：

.\scripts\run_isaac_sim.ps1

腳本會驗證 Isaac Sim 6.0.1、載入 isaac.sim.mcp_extension，並在 127.0.0.1:8766 啟動 TCP Server。

2. 設定 MCP Client

把以下設定加入 MCP Client，並將 command 改成這個 repository 的實際絕對路徑：

{
  "mcpServers": {
    "isaac-sim": {
      "command": "D:\\Dev\\IsaacSim-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "isaac_mcp.server"],
      "env": {
        "ISAAC_MCP_HOST": "127.0.0.1",
        "ISAAC_MCP_PORT": "8766"
      }
    }
  }
}

也可以在第二個 PowerShell 視窗直接啟動 MCP Server：

.\scripts\run_mcp_server.ps1

3. 確認連線

請 MCP Client 呼叫：

get_scene_info

成功時會回傳目前 Stage、asset root 與 prim 數量。

MCP Tools

目前共 45 個 tools：

類別	Tools
場景	get_scene_info, create_physics_scene, clear_scene, list_prims, get_prim_info, list_environments, load_environment
物件	create_object, delete_object, transform_object, clone_object
燈光	create_light, modify_light
材質	create_material, apply_material
機器人	create_robot, list_available_robots, refresh_robot_library, get_robot_info, set_joint_positions, get_joint_positions
人物	spawn_human
感測器	create_camera, capture_image, create_lidar, get_lidar_point_cloud
資產	list_nvidia_assets, spawn_nvidia_asset, import_urdf, load_usd, search_usd, generate_3d
模擬與診斷	play_simulation, pause_simulation, stop_simulation, step_simulation, set_physics_params, get_isaac_logs, get_simulation_state, get_physics_state, get_joint_config, execute_script, reload_script
Action Graph	create_action_graph, edit_action_graph

基本使用範例

建立場景與機器人

依序請 MCP Client 執行：

1. 呼叫 create_physics_scene 建立重力與地面。
2. 呼叫 list_available_robots 查詢正確 robot key。
3. 呼叫 create_robot 建立 Franka。
4. 呼叫 get_robot_info 檢查 articulation 與 DOF。
5. 呼叫 set_joint_positions 設定關節。
6. 呼叫 step_simulation 並觀察 robot prim。

建立 Action Graph

需要反覆修改控制邏輯時，使用本機 script file：

create_action_graph(
  graph_path="/World/RobotController",
  script_file="D:\\Dev\\IsaacSim-MCP\\scripts\\controller.py"
)

修改 script 後呼叫：

reload_script(file_path="D:\\Dev\\IsaacSim-MCP\\scripts\\controller.py")

script_file + reload_script 已在 Isaac Sim 6.0.1 實測通過，適合持續開發。inline ScriptNode 適合短而固定的程式碼。

產生 NVIDIA 人物

人物需要可用 NavMesh。以下會建立 NavMesh volume 並產生一位巡遊人物：

spawn_human(
  count=1,
  behavior="wander",
  auto_create_navmesh_volume=true,
  navmesh_volume_center=[0, 0, 1],
  navmesh_volume_size=[32, 32, 4]
)

需要自訂人物互動時，將 behavior 設為 manual，再搭配 reload_script 控制 IRA Behavior Agent。

建立工廠場景

工廠相關腳本位於 scripts/：

Script	用途
create_factory_scene.py	建立 32 × 32 公尺、10 個工作區與 3 台 AGV 的基本工廠
prepare_factory_assets.py	準備工廠資產
configure_factory_assets_mcp.py	透過 MCP 配置機器手臂、AGV、輸送帶等資產
factory_interaction.py	工廠互動控制
nvidia_human_interaction.py	NVIDIA 人物互動範例
verify_factory_scene.py	驗證工廠數量、配置與 metadata

生成的 USD 與測試輸出會放在 test_outputs/，此資料夾已由 .gitignore 排除。

選用 API 金鑰

一般場景、機器人、人物、感測器與 Action Graph 不需要 API 金鑰。只有以下外部服務需要：

$env:NVIDIA_API_KEY = "你的 NVIDIA API key"
$env:ARK_API_KEY = "你的 Beaver3D API key"

• search_usd 使用 NVIDIA_API_KEY
• generate_3d 使用 ARK_API_KEY，服務端也可能要求 BEAVER3D_MODEL

請勿把金鑰寫進程式碼、README、.env 或 commit。

操作原則與限制

• step_simulation 只能在暫停或停止狀態使用；播放中會明確拒絕。
• Action Graph 使用 execution evaluator，只有 timeline 播放時執行。
• Camera 與 LiDAR 建立後需要播放並暖機數個 frame 才會產生資料。
• set_physics_params 目前直接支援 gravity；time_step 與 gpu_enabled 需使用 execute_script。
• edit_action_graph 可修改一般 attribute 與新增連線；修改 inline ScriptNode.inputs:script 在 6.0.1 仍有限制。
• 載入含 non-manifold collision 的資產可能使 PhysX native plugin 崩潰。先在乾淨 Stage 驗證資產與碰撞設定。
• execute_script 權限很高，只執行可信任程式碼，並避免在 Action Graph 同時控制相同 articulation 時修改它。

測試

安裝開發依賴：

uv sync --dev

執行不需要 Isaac Sim runtime 的測試：

uv run pytest -q --ignore=tests/test_launcher_engine.py --ignore=tests/test_integration.py -k "not test_detect_version_returns_zero_on_failure"
uv run ruff check .
uv run ruff format --check .

完整 MCP live test 需要先啟動 Isaac Sim：

.\.venv\Scripts\python.exe .\scripts\test_all_tools.py

測試結果與限制請見：

• docs/ALL_TOOLS_TEST_REPORT.md
• docs/NVIDIA_ASSET_CATALOG.md

專案結構

IsaacSim-MCP/
├─ isaac_mcp/                 Python MCP Server 與 45 個 tool 定義
├─ isaac.sim.mcp_extension/   Isaac Sim Extension、handlers 與 V5/V6 adapters
├─ scripts/                   Windows/Linux 啟動、工廠與驗證腳本
├─ demo/                      機器人控制範例
├─ test_assets/               小型測試資產與 Action Graph probe
├─ tests/                     自動測試
├─ docs/                      測試報告與 NVIDIA 資產目錄
├─ media/                     README 與展示媒體
├─ pyproject.toml             Python 套件設定
└─ LICENSE                    MIT License

上傳 GitHub

確認測試通過後執行：

git init -b main
git add .
git status
git commit -m "Initial Isaac Sim MCP release"
git remote add origin https://github.com/Tim0320/IsaacSim-MCP.git
git push -u origin main

git status 不應出現 .venv/、test_outputs/、logs/、.env 或 API 金鑰檔案。

授權

本專案使用 MIT License。發布修改版時請保留原授權、copyright notice 與來源歸屬。