BlenderMCP — Blender Model Context Protocol Integration

BlenderMCP connects Blender to AI assistants through the Model Context Protocol (MCP), letting Claude directly control Blender for prompt-assisted 3D modelling, scene creation, rendering, and automation.

This is an extended fork of ahujasid/blender-mcp with 92 tools, full Blender 4.x compatibility, and telemetry removed.

What's new in this fork

• 92 tools across 26 categories (up from the original ~20)

• Blender 4.x compatibility — fixes for BMesh layer API changes, EEVEE engine name, temp_override region requirement, compositor node ordering

• No telemetry — all analytics code removed

• Auto-restart on addon reload — server restarts automatically when the addon is cycled in Preferences; no manual click needed

• deploy.py — one-command script to copy addon.py to Blender's installed addons path

• img_to_3d_server.py — local image-to-3D inference via TripoSR (optional, loads/unloads on demand to free VRAM)

• TOOLS.md — full reference for all 91 tools with parameters

Related MCP server: BlenderMCP

Tool categories (91 tools)

See TOOLS.md for full parameter documentation.

Requirements

• Blender 4.0 or newer (Blender 4.3 recommended)

• Python 3.10+

• uv package manager

Installation

1. Install the MCP server

git clone https://github.com/naab007/blender_mcp
cd blender_mcp
uv venv .venv
uv pip install -e .

2. Install the Blender addon

1. Download addon.py from this repo

2. Open Blender → Edit → Preferences → Add-ons → Install...

3. Select addon.py and enable Interface: Blender MCP

4. In the 3D View sidebar (N), open the BlenderMCP tab and click Start MCP Server

After the first install, use deploy.py to push addon updates in one command:

.venv/Scripts/python.exe deploy.py

Edit the destination path in deploy.py to match your Blender version.

3. Configure your AI client

Claude Code — create .mcp.json in your working directory:

{
  "mcpServers": {
    "blender": {
      "type": "stdio",
      "command": "/path/to/blender_mcp/.venv/Scripts/blender-mcp.exe"
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

Usage

Once the addon is running and the MCP server is configured, ask Claude to:

• "Create a low-poly dungeon scene with a dragon guarding a pot of gold"

• "Set up 3-point studio lighting and render from the active camera"

• "Add a Subdivision Surface modifier to the selected object and apply a PBR material"

• "Capture viewport angles from front, side, and top and give me a contact sheet"

• "Boolean-subtract the sphere from the cube"

• "Download a rock model from PolyHaven and place it at the origin"

• "Generate a 3D model of a garden gnome via Hyper3D"

• "Render depth map of the current scene"

• "Keyframe this object moving from (0,0,0) to (5,0,0) over 60 frames"

• "Compare these two renders and show me exactly what changed" → diff_images(path_a, path_b)

Environment variables

Dependencies

Architecture

Claude / AI client
      │  MCP (stdio)
      ▼
server.py  (FastMCP, @mcp.tool functions)
      │  JSON over TCP :9876
      ▼
addon.py   (Blender Python addon, bpy.app.timers dispatch)
      │
      ▼
Blender scene

• All addon handlers run on Blender's main thread via bpy.app.timers.register() — no threading issues

• Commands are JSON { "type": "...", "params": {...} }, responses are { "status": "success"|"error", "result": ... }

Troubleshooting

• "context is incorrect" on view3d operators — requires Blender 4.x temp_override(area=area, region=region). Already fixed in this fork.

• BLENDER_EEVEE enum not found — use BLENDER_EEVEE_NEXT in Blender 4.x. Already normalized in this fork.

• Render writes nothing after depth map — compositor state corruption from empty node tree. Fixed in this fork via full snapshot/restore in render_depth_map.

• execute_blender_code runs arbitrary Python in Blender — powerful but irreversible. Save your work first.

• Connection issues — ensure the addon server is running (green dot in the BlenderMCP sidebar tab) before sending commands.

License

MIT — see LICENSE.

Based on ahujasid/blender-mcp by Siddharth Ahuja.