Isaac Sim MCP Server

Isaac Sim MCP Server

Controle por linguagem natural para NVIDIA Isaac Sim através do Model Context Protocol (MCP).

Conecte qualquer IDE compatível com MCP (Cursor, VS Code, Claude Code, Windsurf, Antigravity, JetBrains) a uma instância do Isaac Sim em execução e controle-a com comandos em inglês simples — crie robôs, monte cenas, execute simulações e depure física diretamente do seu editor.

Destaques

• 42 ferramentas em 9 categorias — cena, objetos, iluminação, robôs, sensores, materiais, assets, simulação, gráficos
• 107+ robôs descobertos automaticamente da biblioteca de assets do Isaac Sim (Franka, UR, Unitree, Boston Dynamics e outros)
• Depuração passo-a-passo — avance a simulação e inspecione posições de prims, estados de juntas e física em uma única chamada
• Hot-reload — itere em controladores Python sem reiniciar o Isaac Sim
• Multi-instância — execute várias sessões do Isaac Sim lado a lado em portas diferentes
• Desenvolvido para Isaac Sim 5.1.0 - 6.0.1 (PhysX + Newton) com uma camada de adaptadores modular para isolamento de versões

Instalação

Opção A: pip install (recomendado)

pip install isaacsim-mcp-server

Isso instala o servidor MCP e a CLI isaacsim-mcp-server. Você ainda precisa da extensão do Isaac Sim do repositório (veja Iniciando o Isaac Sim abaixo).

Opção B: A partir do código-fonte

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

Requisitos

[!IMPORTANT] Linux e Windows são suportados. No Windows, use o lançador do PowerShell scripts/run_isaac_sim.ps1 no lugar dos scripts .sh (veja abaixo). macOS não é suportado porque o NVIDIA Isaac Sim não roda em macOS.

[!NOTE] Agradecemos contribuições para suportar outras versões do Isaac Sim. A camada de adaptadores foi projetada para facilitar o isolamento de versões.

Início Rápido

1. Configure o ambiente

Se você instalou a partir do código-fonte:

./scripts/setup_python_env.sh

No Windows, uv sync cria o ambiente virtual (.venv) e instala o pacote e suas dependências:

uv sync

2. Inicie o Isaac Sim com a extensão

./scripts/run_isaac_sim.sh

Você deve ver nos logs:

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

O script procura o Isaac Sim em $HOME/isaacsim; defina ISAACSIM_ROOT para usar uma instalação diferente.

Escolhendo o motor de física. O Isaac Sim 6.0+ inclui os backends PhysX (padrão) e Newton. Selecione um com --newton / --physx, ou ISAACSIM_ENGINE:

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

Os mesmos flags funcionam com scripts/launch_isaac_sim_mcp.sh. Todo o resto na linha de comando é encaminhado ao Kit sem alterações. O servidor detecta automaticamente o motor ativo, então não há mudanças de configuração no lado do MCP. O Newton requer 6.0 ou mais recente; solicitá-lo na versão 5.1.0 falha com uma mensagem clara.

No Windows, use o lançador do PowerShell. Ele aceita a mesma seleção de motor e encaminha argumentos extras para o 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

O script resolve a instalação a partir de -IsaacSimRoot, depois $env:ISAACSIM_ROOT, depois uma compilação local do código-fonte, depois C:\isaacsim, depois %USERPROFILE%\isaacsim. Ele também cria um diretório de trabalho USD gravável (.cache\usd) já que o Windows não tem /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. Conecte sua IDE

Adicione o servidor MCP ao seu editor. Substitua o caminho pela localização real do seu repositório. Os exemplos command são para Linux/macOS; cada guia mostra o equivalente Windows, que envolve o lançador do 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. Comece a dar comandos

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].

Arquitetura

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

Ferramentas

42 ferramentas em 9 categorias:

Limitações Conhecidas

Defeitos abertos que uma sessão normal pode encontrar. Cada um é avisado no ponto de uso quando possível; esta lista serve para escolher um runtime antes de começar.

Exemplos de Comandos

Inicialização de cena

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.

Layout de robôs

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].

Carregamento de ambiente

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

Busca de assets e geração 3D

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

Uso Avançado

Múltiplas Instâncias

Execute várias sessões do Isaac Sim lado a lado. Cada uma usa uma porta diferente (atribuída automaticamente a partir de 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" }
    }
  }
}

Lançador de Desktop (Linux)

Instale um ícone de aplicativo dedicado Isaac Sim MCP:

./scripts/install_desktop_entry.sh

Isso cria um lançador que atribui portas automaticamente, aguarda o socket da extensão e limpa ao sair.

Fluxo de Trabalho Recomendado

1. Comece com get_scene_info para verificar a conexão
2. Crie uma cena de física se o palco estiver vazio
3. Prefira ferramentas específicas antes de execute_script
4. Use list_available_robots / list_environments antes de carregar
5. Use create_action_graph para conectar controladores OnPlaybackTick → ScriptNode
6. Use step_simulation com observe_prims e observe_joints para depuração
7. Use reload_script para iterar em controladores sem reiniciar

Demonstração: Franka Pick-and-Place

Uma demonstração pronta para executar em demo/franka_pick_place.py usando RMPflow para planejamento de movimento:

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.

Usa create_action_graph com script_file para configuração de Action Graph + ScriptNode em uma etapa, além das ferramentas de observabilidade: get_joint_config, step_simulation com observe_prims, get_physics_state e edit_action_graph para hot-reload de scripts.

Desenvolvimento

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

O inspetor está disponível em http://localhost:5173.

Notas de Configuração

Substitua os padrões:

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

A seleção do motor está em scripts/lib/isaac_launcher.sh: cada motor mapeia para o script de lançamento que o Isaac Sim inclui para ele. Adicionar uma entrada a esse mapa é tudo que um novo backend precisa — isso habilita tanto ISAACSIM_ENGINE=<name> quanto --<name> em todos os scripts de lançamento.

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

Contribuindo

Pull requests são bem-vindos. Melhorias em ferramentas, documentação, adaptadores e testes são todas úteis.

Licença

MIT License. Copyright (c) 2023-2025 omni-mcp, Copyright (c) 2026 whats2000. Consulte a LICENÇA.