# Blender Codex MCP

Codex MCP server with two execution modes:

- `addon` mode (default): realtime control of the currently open Blender UI scene through a Blender addon.
- `subprocess` mode: headless per-call Blender runs (legacy behavior).

## Folder Layout

- `blender_codex_mcp/`: Python MCP server package
- `blender_addon/__init__.py`: installable Blender addon entry file

## 1) Install MCP Package

```powershell
cd codex_mcp
pip install -e .
```

## 2) Install Blender Addon (Realtime Mode)

1. Create zip file from `blender_addon` directory contents:
```powershell
cd codex_mcp
Compress-Archive -Path blender_addon\* -DestinationPath codex_blender_mcp_addon.zip -Force
```
2. In Blender: `Edit > Preferences > Add-ons > Install...`
3. Select `codex_blender_mcp_addon.zip`.
4. Enable addon: `Codex Blender MCP Bridge`.
5. Open `3D View > Sidebar > Codex MCP` tab.
6. Set host/port (`127.0.0.1:9877`) and press `Start`.

## 3) Configure MCP Server for Addon Mode

Environment variables:

- `BLENDER_MCP_MODE=addon`
- `BLENDER_ADDON_HOST=127.0.0.1`
- `BLENDER_ADDON_PORT=9877`
- `BLENDER_TIMEOUT_SECONDS=60`

Example Codex MCP config:

```json
{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_codex_mcp.server"],
      "env": {
        "BLENDER_MCP_MODE": "addon",
        "BLENDER_ADDON_HOST": "127.0.0.1",
        "BLENDER_ADDON_PORT": "9877",
        "BLENDER_TIMEOUT_SECONDS": "60"
      }
    }
  }
}
```

## 4) Realtime Workflow

1. Open Blender UI normally and load your `.blend`.
2. Start addon server from Blender panel (`Start` button).
3. Start Codex MCP server.
4. Call tools (`blender_add_primitive`, `blender_exec_python`, `blender_scene_info`).
5. Changes appear immediately in the current Blender viewport.

## Viewport Images for Verification

Use MCP tool:

- `blender_capture_viewport(save_path)`

This captures the active `VIEW_3D` viewport and saves a PNG so Codex can inspect design progress and suggest next changes.

## Subprocess Mode (Optional)

Set:

- `BLENDER_MCP_MODE=subprocess`
- `BLENDER_PATH=C:\Program Files\Blender Foundation\Blender 5.0\blender.exe`

This mode does not provide live viewport updates.