Blender MCP setup
Run mcp-for-blender safely with Safe Mode, port 9876 isolation, and 3D draft imports.
Blender MCP (ahujasid/mcp-for-blender, MIT, PyPI mcp-for-blender) bridges Claude, Cursor, VS Code, or Codex to a local Blender instance over a TCP socket on localhost:9876. Install the official Blender Lab MCP add-on (blender.org/lab/mcp-server/) for Blender 5.1+ native workflows, or run uvx mcp-for-blender with BLENDER_MCP_SAFE_MODE=1 enabled so agent Python calls cannot touch files or external networks.
01 / HOW IT WORKS
From setup to a result you can check
01
Choose route
Pick community mcp-for-blender or Official Blender Lab MCP (5.1+).
02
Install addon
Install addon.py in Blender Preferences -> Add-ons and start server.
03
Wire client
Run uvx mcp-for-blender setup or paste JSON into Claude / Cursor.
04
Lock guardrails
Set BLENDER_MCP_SAFE_MODE=1 before granting scene access.
05
Stage assets
Drop in Poly Haven materials or browser GLB drafts via Image3D.
Suggested first-use sequence based on the official documentation. This is not a completed product test.
02 / INSTALL & ADDON PAIRING
Community mcp-for-blender vs Official Blender Lab MCP
Option A: Community mcp-for-blender (broadest asset & generator integrations)
The popular community server (ahujasid/mcp-for-blender, 34,700+ stars, MIT) renamed its PyPI package from blender-mcp to mcp-for-blender. Avoid stale tutorials calling uvx blender-mcp.
One-command guided setup (macOS / Linux / Windows):
# Guided installer CLI
uvx mcp-for-blender setup
# Windows PowerShell installer
irm https://www.mcp-for-blender.com/install.ps1 | iex
# macOS / Linux shell installer
curl -LsSf https://www.mcp-for-blender.com/install.sh | shManual MCP client JSON (Claude Desktop, Cursor, VS Code):
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["mcp-for-blender"],
"env": {
"BLENDER_HOST": "localhost",
"BLENDER_PORT": "9876",
"BLENDER_MCP_SAFE_MODE": "1"
}
}
}
}Download addon.py from github.com/ahujasid/mcp-for-blender, open Blender -> Edit -> Preferences -> Add-ons -> Install from Disk, enable Interface: Blender MCP, and click Connect to MCP server inside the 3D Viewport sidebar (N key).
Option B: Official Blender Lab MCP (blender.org/lab/mcp-server/)
Blender Foundation ships an official experimental MCP server (projects.blender.org/lab/blender_mcp) targeting Blender 5.1+ with native Claude connector packaging. Choose the Official Blender Lab route if your pipeline strictly aligns with Blender Foundation releases; choose mcp-for-blender when you want Poly Haven, Sketchfab, Poly Pizza, Meshy, Tripo, Rodin, Hunyuan3D, or Blender 5.3+ World Labs Gaussian splat integrations out of the box.
03 / SECURITY & SAFE MODE
Restrict execute_blender_code with Safe Mode
By default, Blender MCP exposes execute_blender_code, which runs agent-authored bpy scripts inside Blender’s embedded Python interpreter. Without safeguards, arbitrary Python can call os, subprocess, shutil, or urllib.
Setting BLENDER_MCP_SAFE_MODE=1 restricts file-system writes, subprocess execution, and outbound network sockets inside the executed Blender script block while preserving scene creation, modifiers, shaders, camera framing, and viewport renders.
- Always test in an unsaved or scratch
.blendfile first: undo history (Ctrl+Z) does not automatically protect linked external textures or custom batch exports. - Watch remote asset integrations: Poly Haven, Sketchfab, and paid 3D generator keys (Meshy/Tripo/Rodin) trigger network downloads when enabled in the add-on panel—keep them unchecked until needed.
04 / RAPID ASSET WORKFLOW
Accelerate scene blockouts with image-to-3D .glb drafts
LLMs excel at procedural geometry, lighting rigs, camera keyframes, and shader nodes via bpy, but authoring bespoke hero props from raw Python coordinates takes many slow back-and-forth turns.
A faster hybrid workflow is to generate base props first and refine materials, scale, and lighting through Blender MCP:
- Use Image3D (image3d.io) to convert a single product photo or concept sketch into a clean
.glbor.stlmesh draft in the browser. - Drop the exported
.glbinto your working project directory. - Ask your MCP client to run
bpy.ops.import_scene.gltf(...), normalize scale to real-world meters, attach a three-point lighting rig, and render a studio preview.
For broader scene assembly tips and skill recipes, see our 3dviz-pro-max setup guide and archviz skill profile.
05 / PORT 9876 & SOCKET CONFLICTS
Fix "Connection refused" or silent timeouts on port 9876
1. Only one MCP host at a time: the Blender add-on opens a single-client TCP listener on 127.0.0.1:9876. If Cursor, Claude Desktop, and Claude Code all have "blender" enabled concurrently, the second client hangs or receives connection errors. Close unused MCP clients or override BLENDER_PORT per workspace.
2. Server enabled but not started in Viewport: installing the add-on in Preferences does not start the socket listener. Press N in the 3D Viewport, open the BlenderMCP tab, and click Connect to MCP server.
3. Legacy blender-mcp command fails: update your config from blender-mcp to mcp-for-blender so uvx pulls current MIT releases with BLENDER_MCP_SAFE_MODE support.
06 / QUESTIONS
Before your first session
Why did my old uvx blender-mcp command stop working or miss Safe Mode?
Upstream ahujasid/mcp-for-blender renamed the PyPI distribution from blender-mcp to mcp-for-blender. Update your MCP configuration to run uvx mcp-for-blender and pass BLENDER_MCP_SAFE_MODE=1 in env.
Can Cursor and Claude Code control the same Blender window simultaneously?
No. The Blender MCP add-on socket on localhost:9876 supports one connected MCP client at a time. Disconnect or disable the integration in inactive editors before attaching another host.
Should I use ahujasid/mcp-for-blender or Official Blender Lab MCP?
Use Official Blender Lab MCP if you run Blender 5.1+ and want Blender Foundation’s native Claude connector. Use ahujasid/mcp-for-blender if you want uvx cross-client JSON support, BLENDER_MCP_SAFE_MODE=1, or built-in Poly Haven, Sketchfab, Meshy, Tripo, and Gaussian splat tooling.
07 / SOURCES
Sources and what was not tested
Repository documentation and Blender Lab specifications current as of November 17, 2026. Live 3D execution depends on your local Blender add-on socket, single-client port binding, and workstation GPU/CPU environment.
- ahujasid/mcp-for-blender GitHub repository ↗
- Official Blender Lab MCP documentation ↗
- Blender Lab blender_mcp source repository ↗
- MCP-for-Blender installer docs ↗
- Image3D browser image-to-3D GLB/STL converter ↗