# dcc-mcp-zbrush

> Agent entry point. Read `AGENTS.md` for full navigation map.

## Supported modes

|Mode|When to use|Stack|
|---|---|---|
|**Sidecar + socket plugin (recommended)**|Production GUI and CI clients|External Python → TCP :9876 → <Asset Directory>/Python/init.py → zbrush.commands|
|**Embedded (advanced)**|Pure-Python experiments only|Python plugin inside ZBrush → zbrush.commands|

## Distribution artifacts

There are three independent distribution channels. Each covers a different scope:

|Artifact|Scope|Install command|
|---|---|---|
|**PyPI wheel** (`dcc-mcp-zbrush`)|Python package (src/dcc_mcp_zbrush/) — MCP server, skills, bridge client|`pip install dcc-mcp-zbrush`|
|**Plugin ZIP**|ZBrush plugin files — auto-start package, socket bridge, install scripts|`Download from latest release and run install-windows.ps1 or install-macos.sh`|
|**Repo source**|Everything above + bridge/plugin/ raw sources + tests + tools|`git clone https://github.com/dcc-mcp/dcc-mcp-zbrush.git`|

The wheel does not bundle bridge/plugin/ — that directory is only in the plugin ZIP or the repo checkout.

## Install steps (recommended sidecar)

### Recommended sidecar install (PyPI + plugin ZIP)

1. pip install dcc-mcp-zbrush
2. Download plugin ZIP and run installer in sidecar mode
3. Verify <Asset Directory>/Python/init.py exists
4. Restart ZBrush
5. Run dcc-mcp-zbrush --mode sidecar

### Sidecar from source checkout

1. pip install -e ".[dev]"
2. Copy bridge/plugin/mcp_socket_bridge.py to <Asset Directory>/Python/init.py
3. Restart ZBrush

MCP endpoint: `http://127.0.0.1:9765/mcp`

## MCP config snippets

### Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "dcc-mcp-zbrush": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}
```

### With gateway (multi-DCC)

```json
{
  "mcpServers": {
    "dcc-mcp-zbrush": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}
```

## Environment variables

|Variable|Default|Purpose|
|---|---|---|
|DCC_MCP_ZBRUSH_PORT|`OS-assigned`|Optional fixed MCP instance port|
|DCC_MCP_ZBRUSH_MODE|`auto`|sidecar by default; embedded is advanced and pure-Python only|
|DCC_MCP_ZBRUSH_AUTOSTART|`1`|Auto-start embedded server from plugin|
|DCC_MCP_ZBRUSH_SOCKET_PORT|`9876`|Socket bridge port (sidecar)|
|DCC_MCP_GATEWAY_PORT|`9765`|Gateway election port|
|DCC_MCP_MINIMAL|`1`|Progressive skill loading|

## Bundled skills

|Skill|Tools|
|---|---|
|zbrush-scripting|execute_python, get_session_info|
|zbrush-scene|get_scene_info, list_subtools|
|zbrush-subtool|—|
|zbrush-brush|create_wrinkle_brush, load_wrinkle_brush|
|zbrush-interchange|—|

## Health check

```bash
dcc-mcp-cli list  # discovers the exact OS-assigned instance URL
```

```bash
call_tool("get_session_info")  # reads version + active tool + subtool count
```

```bash
SocketBridge.connect()  # sends JSON-RPC ping → expects {"ok": true}
```

## Common failure modes

|Problem|Likely cause|Fix|
|---|---|---|
|Connection refused|ZBrush not running|Start ZBrush|
|MCP endpoint unreachable|Wrong mode or stale direct URL|Start dcc-mcp-zbrush --mode sidecar, then run dcc-mcp-cli list; socket bridge remains on 9876|
|ZBrushNotAvailableError|Socket bridge plugin not installed|Copy mcp_socket_bridge.py to <Asset Directory>/Python/init.py and restart ZBrush|
|subprocess fails|ZBrush Python VM does not support subprocess|Use execute_python skill instead|
|ZBrush version < 2026.1|No Python SDK available|Upgrade to ZBrush 2026.1+|
