git clone https://github.com/HoldMyBeer-gg/blenderwright.git
cd blenderwright
uv pip install -e .

Then point your client at uv run --directory /path/to/blenderwright blenderwright instead of uvx blenderwright.

If you're developing on blenderwright, symlink the addon folder into Blender's user extensions directory instead. Replace <ver> with your Blender version (e.g. 4.2, 5.1).

# macOS
ln -s "$(pwd)/addon" ~/Library/Application\ Support/Blender/<ver>/extensions/user_default/blenderwright

# Linux
ln -s "$(pwd)/addon" ~/.config/blender/<ver>/extensions/user_default/blenderwright

# Windows (run as admin)
mklink /D "%APPDATA%\Blender Foundation\Blender\<ver>\extensions\user_default\blenderwright" "%cd%\addon"

Then enable the extension in Blender preferences under Get Extensions > User.

claude mcp add blenderwright -- uvx blenderwright

Make sure Blender is running with the addon server started before using the tools.

Usage:

$ claude

> Create a red metallic sphere on a white plane with three-point lighting

> Add a subdivision surface modifier to the sphere and set it to level 3

> Analyze the mesh quality of the sphere and fix any issues

> Set up a turntable animation and render it to /tmp/turntable/

Add blenderwright to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "blenderwright": {
      "command": "uvx",
      "args": ["blenderwright"]
    }
  }
}

Restart Claude Desktop. The Blender tools will appear in the tool list.

blenderwright is a standard MCP server using stdio transport. Any MCP-compatible client can connect by running the server directly:

uvx blenderwright
# or, after pip install blenderwright: blenderwright

The exact config location and format vary by client (typically JSON or TOML under ~/.<client>/). The command is uvx and the args are ["blenderwright"].

The server communicates over stdin/stdout using the MCP protocol. It connects to Blender's addon over TCP on 127.0.0.1:9876 (or your configured port).

1. If the server is running, open the N-panel blenderwright tab and click Stop Server.
2. In Blender, open Edit > Preferences > Get Extensions, find blenderwright, and click Uninstall.
3. Quit and restart Blender (this clears cached blenderwright modules).
4. Install the new .zip via the ▾ > Install from Disk... menu and enable it.

Full reference with every parameter: blenderwright.holdmybeer.gg

• MCP Server (src/blenderwright/): Python process using the mcp SDK. Exposes tools, resources, and prompts over stdio. Validates all inputs before forwarding to Blender.
• Blender Addon (addon/): Runs a TCP socket server inside Blender on a background thread. Commands are queued and executed on the main thread via bpy.app.timers to respect Blender's threading model.
• Render Guard: Tracks render state via bpy.app.handlers. During renders, the server immediately returns a "busy" status. Automatically recovers from crashed renders via load_post handler. Can be force-reset via MCP command.
• Protocol: Length-prefixed JSON messages over TCP with SO_KEEPALIVE for stale connection detection. Each message is a 4-byte big-endian length header followed by a UTF-8 JSON payload.

• Zero telemetry: blenderwright collects no usage data, sends no analytics, and makes no network requests beyond the local TCP connection to Blender.
• Fully local: all communication stays on your machine. No cloud services, no external APIs, no phone-home behavior.
• Open source: the entire codebase is auditable. What you see is what runs.

• Localhost only: The TCP socket binds to 127.0.0.1, never exposed to the network.
• Sandboxed code execution: execute_blender_code blocks 25 dangerous imports (os, subprocess, socket, shutil, sys, ctypes, importlib, pathlib, signal, multiprocessing, pickle, shelve, tempfile, http, urllib, ftplib, smtplib, xmlrpc, code, codeop, compileall, webbrowser, antigravity, turtle, tkinter) and removes dangerous builtins (__import__, exec, eval, compile, open, globals, locals, vars, input, breakpoint, exit, quit, help, memoryview). Safe Blender imports (bpy, bmesh, mathutils, math, json) are allowed.
• Input validation: All inputs pass through validators before reaching Blender: name sanitization, path traversal prevention, numeric range checks, enum allowlists.
• File safety: Import operations disable use_scripts_auto_execute to prevent script injection from imported files. File extensions are checked against allowlists.
• Command allowlist: The addon dispatcher only processes explicitly registered commands. Unknown commands are rejected.
• Shader node allowlist: Only 64 known shader node types can be created, which prevents arbitrary type injection.

• Blender must be running: The MCP server communicates with Blender over TCP. Blender must be open with the addon enabled and server started.
• Single connection: The addon accepts one client connection at a time. Multiple AI assistants cannot control the same Blender instance simultaneously.
• Selection is persistent, not per-call: Selection lives on the mesh in Blender, so it stays set between calls. Choose geometry with the select_* tools, then pass selection="CURRENT" to a mesh tool. The default is still "ALL". Because the selection is shared state, two assistants working on the same mesh would step on each other.
• Sculpt strokes cannot be simulated: You can configure brushes, symmetry, dyntopo, and remeshing, but actual brush strokes are not yet exposed.
• Node graphs require sequential calls: Both shader node trees and geometry node trees must be built one node/connection at a time.
• No undo integration: Operations appear in Blender's undo history individually but there's no MCP-level undo/redo or transaction grouping.
• Viewport capture requires a visible 3D viewport: Headless Blender may not support viewport screenshots.
• No real-time feedback: The MCP protocol is request/response. There's no streaming of viewport updates or render progress.

blenderwright/
├── src/blenderwright/          # MCP server
│   ├── server.py           # FastMCP entry point
│   ├── connection.py       # TCP client to Blender (with busy-retry)
│   ├── validators.py       # Input validation
│   ├── tools/              # 27 tool modules (186 tools)
│   ├── resources/          # MCP resources (scene, objects, materials)
│   └── prompts/            # 12 expert prompt templates
├── addon/                  # Blender addon (zero external deps)
│   ├── blender_manifest.toml  # Blender 4.2+ Extension manifest
│   ├── __init__.py         # bl_info (legacy fallback) + register/unregister
│   ├── server.py           # TCP socket server (SO_KEEPALIVE)
│   ├── dispatcher.py       # Command routing + allowlist
│   ├── thread_safety.py    # Main-thread execution queue
│   ├── render_guard.py     # Render state tracking + crash recovery
│   ├── ui_panel.py         # N-panel UI (start/stop + port config)
│   └── handlers/           # 23 handler modules
└── tests/                  # 1186 unit tests