SKILLSHUB / AGENT TOOLS

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

  1. 01

    Choose route

    Pick community mcp-for-blender or Official Blender Lab MCP (5.1+).

  2. 02

    Install addon

    Install addon.py in Blender Preferences -> Add-ons and start server.

  3. 03

    Wire client

    Run uvx mcp-for-blender setup or paste JSON into Claude / Cursor.

  4. 04

    Lock guardrails

    Set BLENDER_MCP_SAFE_MODE=1 before granting scene access.

  5. 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):

NOT EXECUTED FOR THIS GUIDE
# 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 | sh

Manual MCP client JSON (Claude Desktop, Cursor, VS Code):

NOT EXECUTED FOR THIS GUIDE
{
  "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 .blend file 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:

  1. Use Image3D (image3d.io) to convert a single product photo or concept sketch into a clean .glb or .stl mesh draft in the browser.
  2. Drop the exported .glb into your working project directory.
  3. 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.

Related guides