Isaac Sim MCP Server

Servidor MCP de Isaac Sim

Control por lenguaje natural para NVIDIA Isaac Sim a través del Model Context Protocol (MCP).

Conecta cualquier IDE compatible con MCP (Cursor, VS Code, Claude Code, Windsurf, Antigravity, JetBrains) a una instancia de Isaac Sim en ejecución y contrólala con instrucciones en inglés sencillo: crea robots, construye escenas, ejecuta simulaciones y depura física, todo desde tu editor.

Características destacadas

• 42 herramientas en 9 categorías: escena, objetos, iluminación, robots, sensores, materiales, activos, simulación, gráficos
• Más de 107 robots descubiertos automáticamente desde la biblioteca de activos de Isaac Sim (Franka, UR, Unitree, Boston Dynamics y más)
• Depuración paso a paso y observación: avanza la simulación e inspecciona posiciones de prims, estados de articulaciones y física en una sola llamada
• Recarga en caliente: itera sobre controladores Python sin reiniciar Isaac Sim
• Multi-instancia: ejecuta múltiples sesiones de Isaac Sim en paralelo en diferentes puertos
• Diseñado para Isaac Sim 5.1.0 - 6.0.1 (PhysX + Newton) con una capa de adaptadores modular para aislamiento de versiones

Instalación

Opción A: instalación con pip (recomendada)

pip install isaacsim-mcp-server

Esto instala el servidor MCP y la CLI isaacsim-mcp-server. Aún necesitas la extensión de Isaac Sim del repositorio (consulta Iniciar Isaac Sim más abajo).

Opción B: desde el código fuente

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

Requisitos

[!IMPORTANTE] Linux y Windows son compatibles. En Windows, usa el lanzador de PowerShell scripts/run_isaac_sim.ps1 en lugar de los scripts .sh (consulta más abajo). macOS no es compatible porque NVIDIA Isaac Sim no se ejecuta en macOS.

[!NOTA] Agradecemos contribuciones para admitir otras versiones de Isaac Sim. La capa de adaptadores está diseñada para un aislamiento sencillo de versiones.

Inicio rápido

1. Configura el entorno

Si instalaste desde el código fuente:

./scripts/setup_python_env.sh

En Windows, uv sync crea el entorno virtual (.venv) e instala el paquete junto con sus dependencias:

uv sync

2. Inicia Isaac Sim con la extensión

./scripts/run_isaac_sim.sh

Deberías ver en los registros:

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

El script busca Isaac Sim en $HOME/isaacsim; establece ISAACSIM_ROOT para usar una instalación diferente.

Elección del motor de física. Isaac Sim 6.0+ incluye los motores PhysX (predeterminado) y Newton. Selecciona uno con --newton / --physx, o ISAACSIM_ENGINE:

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

Las mismas opciones funcionan con scripts/launch_isaac_sim_mcp.sh. Todo lo demás en la línea de comandos se reenvía a Kit sin cambios. El servidor detecta automáticamente el motor activo, por lo que no se requieren cambios de configuración en el lado de MCP. Newton requiere 6.0 o posterior; solicitarlo en 5.1.0 falla con un mensaje claro.

En Windows, usa el lanzador de PowerShell en su lugar. Acepta la misma selección de motor y reenvía argumentos adicionales a 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

El script resuelve la instalación desde -IsaacSimRoot, luego $env:ISAACSIM_ROOT, luego una compilación local del código fuente, luego C:\isaacsim, luego %USERPROFILE%\isaacsim. También crea un directorio de trabajo USD escribible (.cache\usd) ya que Windows no tiene /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. Conecta tu IDE

Agrega el servidor MCP a tu editor. Reemplaza la ruta con la ubicación real de tu repositorio. Los ejemplos de command son para Linux/macOS; cada guía muestra el equivalente Windows, que envuelve el lanzador de 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. Comienza a dar instrucciones

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

Arquitectura

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

Herramientas

42 herramientas en 9 categorías:

Limitaciones conocidas

Defectos abiertos que una sesión normal puede encontrar. Cada uno se advierte en el punto de uso cuando es posible; esta lista es para elegir un entorno de ejecución antes de comenzar.

Ejemplos de instrucciones

Inicialización de escena

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.

Disposición de robots

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

Carga de entornos

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

Búsqueda de activos y generación 3D

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

Uso avanzado

Múltiples instancias

Ejecuta múltiples sesiones de Isaac Sim en paralelo. Cada una usa un puerto diferente (asignado automáticamente desde 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" }
    }
  }
}

Lanzador de escritorio (Linux)

Instala un icono de aplicación dedicado Isaac Sim MCP:

./scripts/install_desktop_entry.sh

Esto crea un lanzador que asigna puertos automáticamente, espera el socket de la extensión y limpia al salir.

Flujo de trabajo recomendado

1. Comienza con get_scene_info para verificar la conexión
2. Crea una escena de física si el escenario está vacío
3. Prefiere herramientas específicas antes de execute_script
4. Usa list_available_robots / list_environments antes de cargar
5. Usa create_action_graph para conectar controladores OnPlaybackTick → ScriptNode
6. Usa step_simulation con observe_prims y observe_joints para depurar
7. Usa reload_script para iterar sobre controladores sin reiniciar

Demo: Franka Pick-and-Place

Una demo lista para ejecutar en demo/franka_pick_place.py que usa RMPflow para planificación de movimiento:

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 con script_file para la configuración de Action Graph + ScriptNode en un solo paso, además de las herramientas de observabilidad: get_joint_config, step_simulation con observe_prims, get_physics_state y edit_action_graph para recarga en caliente de scripts.

Desarrollo

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

El inspector está disponible en http://localhost:5173.

Notas de configuración

Anula los valores predeterminados:

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

La selección de motor reside en scripts/lib/isaac_launcher.sh: cada motor se asigna al script de lanzamiento que Isaac Sim incluye para él. Agregar una entrada a ese mapa es todo lo que necesita un nuevo backend: habilita tanto ISAACSIM_ENGINE=<name> como --<name> en cada script de lanzamiento.

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

Contribuciones

Las solicitudes de extracción son bienvenidas. Las mejoras a herramientas, documentación, adaptadores y pruebas son todas útiles.

Licencia

MIT License. Copyright (c) 2023-2025 omni-mcp, Copyright (c) 2026 whats2000. Consulta LICENSE.