# NVIDIA Isaac MCP

MCP (Model Context Protocol) server for NVIDIA Isaac Sim & Isaac Lab — enables AI tools like Windsurf, Claude Desktop, and Claude Code to control Isaac Sim through natural language.

## Architecture

```
AI Client (Windsurf/Claude)  ←— MCP (stdio) —→  nvidia-isaac-mcp (this package)
                                                       │
                                                  TCP Socket :9876
                                                       │
                                                  isaacsim.mcp.server
                                                  (Extension inside Isaac Sim)
```

Two components:

1. **Isaac Sim Extension** (`exts/isaacsim.mcp.server/`) — runs inside Isaac Sim, listens on TCP port 9876
2. **MCP Server** (`src/nvidia_isaac_mcp/`) — external Python process that AI tools connect to

## Prerequisites

- NVIDIA Isaac Sim 5.x
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (recommended)

## Setup

### 1. Start Isaac Sim with the extension

```bash
cd <your-isaac-sim-install>
bash isaac-sim.sh \
    --ext-folder <path-to-nvidia-isaac-mcp>/exts \
    --enable isaacsim.mcp.server
```

The extension will start listening on `127.0.0.1:9876`.

### 2. Run the MCP server

```bash
cd <path-to-nvidia-isaac-mcp>
uv run nvidia-isaac-mcp
```

### 3. Configure your AI tool

**Windsurf / Claude Desktop** — add to MCP settings:

```json
{
    "mcpServers": {
        "isaac-sim": {
            "command": "uv",
            "args": ["run", "--directory", "<path-to-nvidia-isaac-mcp>", "nvidia-isaac-mcp"]
        }
    }
}
```

## Available Tools

### Core
| Tool | Description |
|---|---|
| `ping` | Check connectivity to Isaac Sim and return server version |

### Scene Inspection
| Tool | Description |
|---|---|
| `get_stage_info` | Overview of the current USD stage (prims, up-axis, etc.) |
| `get_prim_info` | Detailed info about a specific prim (attributes, transform, children) |

### Prim CRUD
| Tool | Description |
|---|---|
| `create_prim` | Create a USD prim (Cube, Sphere, Cylinder, Cone, Plane, Capsule, Xform) |
| `modify_prim` | Modify a prim's transform or visibility |
| `delete_prim` | Remove a prim from the stage |

### Code Execution
| Tool | Description |
|---|---|
| `execute_code` | Run arbitrary Python code inside Isaac Sim's runtime |

### Physics & Simulation
| Tool | Description |
|---|---|
| `create_physics_scene` | Create a PhysicsScene prim to enable simulation |
| `add_rigid_body` | Add rigid body physics to an existing prim |
| `add_ground_plane` | Add a physics-enabled ground plane |
| `simulation_control` | Play, pause, or stop the simulation |

### Robots & Assets
| Tool | Description |
|---|---|
| `spawn_robot` | Spawn a built-in robot (franka, ur10, jetbot, etc.) |
| `list_available_robots` | List available built-in robot assets |
| `load_usd_asset` | Load any USD file as a reference into the stage |

## Testing

```bash
# Direct TCP test (no MCP server needed, just the extension)
python tests/test_e2e.py

# MCP inspector
uv run mcp dev src/nvidia_isaac_mcp/server.py
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `ISAAC_SIM_HOST` | `127.0.0.1` | Extension socket host |
| `ISAAC_SIM_PORT` | `9876` | Extension socket port |