MCP Blender · Ariel Shemesh

What it is

BlenderMCP (ahujasid/blender-mcp) is a two-piece bridge: an MCP server you run via uvx, plus a Blender addon that opens a socket on the Blender side. Claude Desktop becomes a co-pilot inside your .blend file — it can create geometry, apply materials, run arbitrary Python in Blender, fetch Poly Haven assets, and call Hyper3D Rodin to generate brand-new 3D models from a prompt.

Architecture

Claude Desktop ──MCP──> blender-mcp (uvx, on your machine)
                            │
                            │  TCP socket (default 9876)
                            ▼
                   Blender + addon.py (3D View > "Connect to Claude")

The addon registers an MCP-aware panel inside Blender’s 3D View sidebar; clicking “Connect to Claude” opens the local socket the MCP server talks to. Two environment variables tweak the wiring: BLENDER_HOST (default localhost) lets you point the MCP server at a Blender running in a different process or container, and BLENDER_PORT (default 9876) swaps the port when 9876 is taken. For a Docker workflow you typically set BLENDER_HOST=host.docker.internal.

The wire protocol is plain JSON over TCP: commands are {type, params}, responses are {status, result|message}. That means you can poke the addon directly from a Python REPL or a shell script if you want to debug without going through the LLM — helpful when something is misbehaving and you need to isolate which side dropped the call.

Install

Prerequisites: Blender 3.0+, Python 3.10+, the uv package manager.

# Install uv (one-liner)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the addon
# 1. Download addon.py from github.com/ahujasid/blender-mcp
# 2. In Blender: Edit → Preferences → Add-ons → Install...
# 3. Pick the downloaded addon.py
# 4. Enable the "Interface: Blender MCP" checkbox
# 5. In the 3D View sidebar, click "Connect to Claude"

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — the analogous path on Windows or Linux:

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

Restart Claude Desktop. A new “tool” group appears in the chat composer: BlenderMCP.

What Claude can do once connected

Create, delete, modify shapes — primitives, transforms, parenting, modifiers.
Apply or create materials — nodes, principled BSDF setups, texture loading.
Execute any Python in Blender — the full bpy API surface; this is the escape hatch.
Inspect the scene — what’s in the outliner, what each object looks like, what materials are bound.
Poly Haven — “Download the right models, assets and HDRIs through Poly Haven.”
Sketchfab — search and download models from the Sketchfab library (added in 1.5.x).
Hyper3D Rodin — generate brand-new 3D models from a text prompt and drop them into the active scene.
Hunyuan3D — Tencent’s text-to-3D model, supported alongside Rodin.
Viewport screenshots — Claude can take a snapshot of the 3D viewport to understand what the scene currently looks like.

Usage examples

# In a Claude Desktop chat once BlenderMCP is connected:

"Make me a low-poly desk scene: a wooden desk,
 a monitor, a coffee mug. Apply a wood material to the desk
 and a matte black plastic to the monitor."

"Download a Poly Haven HDRI for an overcast outdoor scene
 and use it as world lighting."

"Use Hyper3D Rodin to generate a model of a vintage Polaroid
 camera, then place it on the desk facing the monitor."

"Render the current view at 1920x1080 with 128 samples and
 save to /tmp/desk-render.png."

A few prompts I have used on real projects:

“Create a low-poly scene in a dungeon, with a dragon guarding a pot of gold” — one of the README’s demo prompts, and it works as written. The Hyper3D Rodin call returns a usable dragon mesh in roughly a minute; ahujasid’s YouTube walkthrough has the full clip.
“Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven” — Poly Haven’s API gives Claude HDRI sky, ground textures and prop models in one pass.
“Get information about the current scene, and make a threejs sketch from it” — scene inspection → export → code-gen, all in one chat.
“Reference image attached — build a Blender scene that matches it” — works because the viewport-screenshot tool gives Claude a feedback signal it can compare against the input image.

Why this matters

Most “AI in Blender” demos are screenshots from a chatbot reading a Python snippet you then paste in by hand. BlenderMCP closes that loop — Claude executes bpy calls against your actual file, sees what it produced, and iterates. The combination of scene inspection + arbitrary Python + viewport screenshots means “build this scene for me” is one prompt, not a tutorial.

The tight feedback loop is the part that actually changes the workflow. Claude proposes a script, runs it, asks for a viewport screenshot, sees the wood material reading as cardboard, swaps the roughness, re-renders, moves on. None of that is theoretically novel — bpy has always been there — but the difference between “copy this 40-line snippet into the scripting tab” and “please darken the desk wood and try again” is the difference between a tutorial and a tool.

For asset sourcing the Poly Haven + Sketchfab + Hyper3D Rodin combo means Claude rarely has to fall back on procedural primitives when you want something specific. “Drop a worn leather couch on the floor” goes Sketchfab; “use an overcast HDRI” goes Poly Haven; “a vintage Polaroid camera” goes Rodin. The model picks the right source based on whether you asked for a real-world reference asset or a generated novel one.

Safety & constraints

Three things to keep in mind before you point an LLM at a .blend file you care about:

Arbitrary Python is arbitrary Python. The execute_blender_code tool can run anything bpy exposes — including filesystem writes, modal operators that hang the UI, and changes that are hard to roll back. Save before every non-trivial prompt.
One MCP server at a time. The README is explicit: do not run BlenderMCP from Claude Desktop and Cursor simultaneously. The socket on port 9876 is single-client, and two clients fighting over it produces nothing useful.
Poly Haven downloads count. Poly Haven assets are pulled to disk on every request. Turn the checkbox off in the Blender N-panel when you do not want network traffic, and Claude will route around it.

BlenderMCP also collects anonymous telemetry by default. You can opt out from the addon preferences or by setting DISABLE_TELEMETRY=true in the MCP env block — the README documents both paths.

Alternative servers

The Blender + MCP space already has more than one implementation. The most useful comparison points right now:

djeada/blender-mcp-server — a tighter, more opinionated alternative: 27 tools across 7 namespaces (scene inspection, object manipulation, materials, rendering/export, history, Python exec, async jobs). Adds safety features ahujasid lacks: a Safe Mode that restricts file I/O to the project directory, a tool whitelist, script path restrictions, and a module blocklist (subprocess, shutil, socket, webbrowser, ctypes, multiprocessing are blocked by default).
dhakalnirajan/blender-open-mcp — a fork wired to local Ollama models instead of cloud LLMs. The right pick when you cannot or will not send .blend content to a third-party API.
blender.org/lab/mcp-server — Blender Foundation’s own experimental MCP exploration. Worth watching, not yet the default.

Source

Repo: github.com/ahujasid/blender-mcp (current version 1.5.5, with Hunyuan3D, Sketchfab search, Poly Haven and Hyper3D Rodin support). Alternative builds: djeada/blender-mcp-server (27 tools across 7 namespaces — scene inspection, object manipulation, materials, rendering/export, history, Python exec, async jobs), dhakalnirajan/blender-open-mcp (Ollama). Official: blender.org/lab/mcp-server. License: MIT.

API & MCPMCPBlender3D