ZBrush MCP Server

AI-powered control of ZBrush through the Model Context Protocol (MCP).

Overview

This project enables AI agents to control ZBrush programmatically, providing comprehensive access to:

• Scene Management - Create, load, save projects
• Subtool Operations - List, select, create, duplicate, delete subtools
• Transform Operations - Move, rotate, scale with precision
• Sculpting - Select brushes, adjust settings, perform strokes
• Mesh Operations - Subdivide, decimate, Dynamesh, ZRemesher
• Masking - Mask all, clear, invert, mask by features
• Materials & Textures - Apply materials, polypaint, generate maps
• Rendering & Export - BPR render, viewport capture, mesh export
• Timeline & Animation - Keyframes, turntable renders
• Batch Operations - Process multiple subtools efficiently

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   AI Agent  │────▶│  MCP Server │────▶│   Bridge    │────▶│   ZBrush    │
│ (agent.py)  │◀────│(mcp_server) │◀────│  (socket/   │◀────│  (Plugin)   │
└─────────────┘     └─────────────┘     │  file/batch)│     └─────────────┘
                                        └─────────────┘

Prerequisites

• ZBrush 2024+ with Python SDK support
• Python 3.10+
• OpenRouter API Key (for the test agent)

Installation

1. Clone and Install Dependencies

git clone <repository-url>
cd zbrush-agent
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your settings

3. Install ZBrush Plugin

Copy zbrush_plugin/mcp_bridge.py to your ZBrush plugins directory:

macOS:

cp zbrush_plugin/mcp_bridge.py ~/Library/Application\ Support/ZBrush/ZStartup/ZPlugs64/

Windows:

copy zbrush_plugin\mcp_bridge.py "C:\Users\<username>\Documents\ZBrushData\ZStartup\ZPlugs64\"

Or set the ZBRUSH_PLUGIN_PATH environment variable.

Usage

1. Start ZBrush

Launch ZBrush. The MCP bridge plugin will automatically start and listen on port 9876.

2. Run the Test Agent

python agent.py

Optionally specify a different model:

python agent.py --model "openai/gpt-4o"
python agent.py --model "anthropic/claude-sonnet-4"

3. Interact with ZBrush

Example commands:

> List all subtools in the current project
> Create a new sphere subtool and name it "Head"
> Subdivide the current subtool 2 times
> Apply Dynamesh at resolution 256
> Show me the viewport
> Export the mesh as OBJ to /tmp/model.obj

Bridge Modes

The MCP server supports three communication modes:

Socket Mode (Default)

Direct TCP socket connection to ZBrush plugin.

ZBRUSH_BRIDGE_MODE=socket
ZBRUSH_HOST=localhost
ZBRUSH_PORT=9876

File Mode

File-based polling for environments where sockets are restricted.

ZBRUSH_BRIDGE_MODE=file
ZBRUSH_FILE_DIR=/tmp/zbrush_mcp

Batch Mode

Launches ZBrush in batch mode for each command. Slowest but most isolated.

ZBRUSH_BRIDGE_MODE=batch
ZBRUSH_PATH=/path/to/ZBrush

Visual Feedback

The zbrush_see_viewport tool captures the current ZBrush viewport as an image, enabling multimodal AI models to:

• Verify sculpting results
• Check mesh topology
• Inspect material application
• Guide iterative workflows

Project Structure

zbrush-agent/
├── src/zbrush_mcp/           # Client library
│   ├── __init__.py
│   ├── client.py             # Main ZBrush client
│   ├── models.py             # Pydantic models
│   └── modules/              # Operation modules
│       ├── bridge.py         # Communication bridges
│       ├── scene.py          # Scene operations
│       ├── subtool.py        # Subtool operations
│       ├── transform.py      # Transform operations
│       ├── sculpting.py      # Sculpting operations
│       ├── mesh.py           # Mesh operations
│       ├── masking.py        # Masking operations
│       ├── material.py       # Material operations
│       ├── render.py         # Render operations
│       ├── timeline.py       # Timeline operations
│       └── batch.py          # Batch operations
├── zbrush_plugin/            # ZBrush plugin
│   └── mcp_bridge.py         # Socket server plugin
├── agents/                   # Agent prompts
│   └── zbrush.md
├── mcp_server.py             # MCP server
├── agent.py                  # Test agent
├── requirements.txt
├── .env.example
└── README.md

Troubleshooting

Connection Refused

1. Ensure ZBrush is running
2. Check that the plugin loaded (look for "ZBrush MCP Bridge started" in ZBrush)
3. Verify port 9876 is not blocked

Plugin Not Loading

1. Check ZBrush version supports Python SDK (2024+)
2. Verify plugin path is correct
3. Check ZBrush console for errors

Commands Timing Out

1. Increase ZBRUSH_TIMEOUT value
2. For heavy operations (ZRemesher, etc.), timeouts are expected
3. Consider using batch mode for long operations

License

MIT