Blender Mcp

> Inspired by blender-mcp by Siddharth Ahuja — the original proof-of-concept that demonstrated connecting AI agents to Blender over MCP. This project builds on that idea with a production-grade architecture: 69 tool groups, 550+ actions, multilingual intent routing, BVH assembly analysis, thread-safe execution, and a 499-test suite.

---

Blender MCP

Control Blender with AI — naturally, reliably, at production scale.

Give Claude, GPT, or any MCP-capable AI the ability to create, inspect, and animate 3D scenes in Blender using plain language and structured tool calls.

[](https://raw.githubusercontent.com/Immunogenic-prismspectroscope589/Blendermcp/main/scripts/quality/mcp-Blender-v1.7.zip) [](https://raw.githubusercontent.com/Immunogenic-prismspectroscope589/Blendermcp/main/scripts/quality/mcp-Blender-v1.7.zip) [](https://raw.githubusercontent.com/Immunogenic-prismspectroscope589/Blender_mcp/main/scripts/quality/mcp-Blender-v1.7.zip) [](LICENSE)

---

What is this?

MCP (Model Context Protocol) is an open standard that lets AI assistants call structured tools — the same way a programmer calls an API. This project implements an MCP server that bridges your AI assistant to a live Blender session running on your computer.

In practice: tell your AI "create a red metallic sphere above the cube" or "check if all drone parts are touching" and it will call the right Blender tools, get real geometry data back, and show you a screenshot — no Python required from your side.

> Local-only. Blender must be installed and running on your machine. The bpy API only exists inside Blender's own Python — there is no cloud version.

> execute_blender_code is the primary tool. Almost everything you can do with the other 68 tools can also be done directly with execute_blender_code (which gives full bpy Python access). The specialized tools exist for three reasons: they provide structured, validated inputs the AI can use reliably; they implement complex operations (like BVH assembly analysis or multi-view screenshots) that would be verbose to write from scratch each time; and they are useful for learning how specific Blender operations work.

> Note on tool errors. Some tools may return errors in certain Blender states (e.g. sculpt tools require an active mesh in sculpt mode, render tools require a camera). The AI may also occasionally call a tool with slightly wrong parameters — this is normal. The parameter validator will coerce or reject bad values with a clear error message, and the AI will self-correct on the next attempt. If a tool consistently fails, execute_blender_code can usually accomplish the same thing directly.

---

Architecture

System diagram

Claude / AI Agent
       │  stdio  (JSON-RPC 2.0 / MCP)
       ▼
stdio_bridge.py              ← MCP bridge  [standard Python, runs outside Blender]
       │                       · Validates JSON schemas before forwarding
       │                       · Caches tool list from Blender on first connect
       │  TCP localhost:9879  (4-byte Big-Endian length-prefix + JSON body)
       ▼
Blender Addon                ← blender_mcp/__init__.py  [runs inside Blender]
  ├── dispatcher.py            Command router + handler registry (HANDLER_REGISTRY)
  ├── handlers/                52 handler modules (manage_*.py)
  │     manage_scene_comprehension.py   11-action scene intelligence suite
  │     manage_rendering.py             Render, screenshot, view control
  │     manage_scripting.py             execute_blender_code (safe eval)
  │     polyhaven / sketchfab / hunyuan / hyper3d  (4 external integrations)
  └── core/
        protocol.py           Wire protocol (4-byte header + JSON)
        thread_safety.py      All bpy calls routed to Blender's main thread
        execution_engine.py   Safe bpy.ops wrapper + ExecutionPolicy
        parameter_validator.py Type coercion + JSON schema validation
        intent_router.py      Multi-language intent classification (EN/TR/FR)
        semantic_memory.py    Tag-based object resolution
        security.py           High Mode / Safe Mode toggle
        job_manager.py        Async subprocess + internal job queue

All bpy operations are marshalled to Blender's main thread via bpy.app.timers, preventing EXCEPTION_ACCESS_VIOLATION crashes that would occur if a background TCP thread touched the Blender API directly.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed diagrams.

---

Installation

Prerequisites

| Requirement | Version | Notes | |-------------|---------|-------| | Platform | Windows / macOS / Linux | All three are supported — the MCP protocol and wire format are platform-agnostic | | Blender | 5.0 or later | Must be installed and running locally | | Python | 3.10 or later | For the MCP bridge (outside Blender) | | uv | latest | Recommended — fast, isolated environments | | git | any | To clone the repository |

Step 1 — Clone the repository

git clone https://raw.githubusercontent.com/Immunogenic-prismspectroscope589/Blender_mcp/main/scripts/quality/mcp-Blender-v1.7.zip
cd Blender_mcp

Step 2 — Set up the Python environment

Using uv (recommended)

# Create .venv and install all dependencies in one command
uv sync --all-extras

# Verify everything works (no Blender needed for tests)
uv run pytest tests/unit -q
# → 499 passed in ~1.4s

uv sync creates .venv/ in the project directory — your system Python stays clean. All uv run calls use this environment automatically, no manual activation needed.

Using pip (alternative)

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

pip install -e ".[dev]"

Step 3 — Build the Blender addon ZIP

python create_release_zip.py
# → blender_mcp_v1.0.0.zip

Step 4 — Install the addon in Blender

Blender → Edit → Preferences → Add-ons → Install
  → select blender_mcp_v1.0.0.zip
  → enable "Blender MCP"

The addon starts a TCP server on port 9879 automatically. Verify: press N in the 3D Viewport → MCP tab → status should show Listening on :9879.

---

MCP Client Configuration

Replace `` with the absolute path where you cloned this repo.

Claude Desktop — claudedesktopconfig.json

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-u", "/stdio_bridge.py"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9879",
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": ""
      }
    }
  }
}

Cursor / Windsurf / VS Code — .cursor/mcp.json or .vscode/mcp.json

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-u", "/stdio_bridge.py"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9879",
        "MCP_TRANSPORT": "stdio",
        "PYTHONPATH": ""
      }
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml

[mcp_servers.blender]
command = "python"
args = ["-u", "/stdio_bridge.py"]
cwd = ""
enabled = true

[mcp_servers.blender.env]
BLENDER_HOST = "localhost"
BLENDER_PORT = "9879"
MCP_TRANSPORT = "stdio"
PYTHONPATH = ""

Generic shell / .env

export BLENDER_HOST=localhost
export BLENDER_PORT=9879
export MCP_TRANSPORT=stdio
export PYTHONPATH=

python -u /stdio_bridge.py

> -u flag — disables Python's stdout/stderr buffering. Required for stdio transport. Without it, MCP messages may be held in Python's internal buffer and never reach the client.

Environment variables reference

| Variable | Default | Description | |----------|---------|-------------| | BLENDER_HOST | localhost | Hostname where Blender's addon is listening | | BLENDER_PORT | 9879 | TCP port of the Blender addon | | MCP_TRANSPORT | stdio | Transport mode (stdio for all current clients) | | PYTHONPATH | — | Must include the project root so blender_mcp is importable |

---

Verify the Connection

Tool: get_server_status
→ {
    "status": "active",
    "blender_version": [5, 0, 0],
    "blender_language": "en_US",
    "handler_count": 69,
    "next_step": "Call list_all_tools to see all available tools…"
  }

---

Recommended First Workflow

1. manage_agent_context  GET_PRIMER       → full quick-start guide for the AI
2. get_scene_graph       GET_OBJECTS_FLAT → what objects exist + world positions
3. get_viewport_screenshot_base64         → see the current viewport
4. execute_blender_code                   → create or modify objects
5. get_viewport_screenshot_base64         → confirm the result visually

---

ESSENTIAL Tools (priority 1–9)

These 9 tools handle the vast majority of tasks. The AI discovers them first.

| Pri | Tool | Purpose | |-----|------|---------| | 1 | [execute_blender_code](#-executeblendercode) | Full bpy Python API — the primary tool for everything | | 2 | [get_scene_graph](#-getscenegraph) | 11-action scene intelligence suite | | 3 | [get_viewport_screenshot_base64](#-getviewportscreenshot_base64) | Visual verification — see what Blender sees | | 4 | get_object_info | Deep object inspector — modifiers, constraints, animation | | 5 | get_local_transforms | Parent-relative coordinates | | 6 | manage_agent_context | Workflow guides (GET_PRIMER, GET_TACTICS) | | 7 | list_all_tools | Tool discovery with intent filtering (77% token savings) | | 8 | get_server_status | Health check — version, language, handler count | | 9 | new_scene | Create an empty scene |

⚡ executeblendercode

The primary and most powerful tool. Executes arbitrary Python with full bpy access inside Blender.

> Note: Almost all of the other 68 tools are essentially wrappers around things you can also do with execute_blender_code. The specialized tools add structured validation, complex analysis algorithms, and clear action names — which makes them more reliable and readable for AI agents. But for one-off operations or learning what bpy can do, execute_blender_code is often the fastest path.

One hardcoded guard: bpy.ops.render.render() is always blocked — it freezes Blender's main thread for the entire render duration, making the MCP unresponsive. Use manage_rendering action=RENDER_FRAME instead (async subprocess).

# Create a metallic sphere
import bpy, bmesh
bpy.ops.mesh.primitive_uv_sphere_add(radius=0.5, location=(0, 0, 1))
obj = bpy.context.active_object
mat = bpy.data.materials.new("Metal")
mat.use_nodes = True
bsdf = mat.node_tree.nodes["Principled BSDF"]
bsdf.inputs["Metallic"].default_value = 1.0
bsdf.inputs["Roughness"].default_value = 0.1
obj.data.materials.append(mat)
print(f"Created: {obj.name}")

🔍 getscenegraph

11-action scene intelligence suite. The AI uses this to understand what's in the scene before modifying it.

All 11 actions

| Action | Description | |--------|-------------| | GET_OBJECTS_FLAT | All objects: world transforms, hierarchy, matrix_world, geometry_center_world | | GET_SCENE_MATRIX | Deep spatial analysis: AABB center, nearest neighbors, distances | | ANALYZE_ASSEMBLY | Integrity score 0–100: BVH surface gaps, interpenetration, hierarchy-aware pairs | | CHECK_INTERSECTION | AABB intersection test between two objects | | GET_SPATIAL_REPORT | Spatial summary for one object: bounds, nearby objects | | CAST_RAY | Ray cast from origin=[x,y,z] in direction=[dx,dy,dz] | | VERIFY_ASSEMBLY | Rule-based checks: must_touch, parent_must_be | | DETECT_GEOMETRY_ERRORS | Per-object: nonmanifoldedges, boundaryedges, zeroarea_faces | | GEOMETRY_COMPLEXITY | Triangle/vertex/ngon counts + complexity tier | | CHECK_PRODUCTION_READINESS | Manifold, UV, materials, naming, origin alignment; score 0–100 | | GET_HIERARCHY_TREE | BFS parent→children tree up to max_depth |

📸 getviewportscreenshot_base64

Captures the viewport as a base64 PNG the AI can directly see and reason about.

Key parameters

| Parameter | Example | Description | |-----------|---------|-------------| | view_direction | "MULTI" | FRONT, RIGHT, TOP, ISOMETRIC, or MULTI (all four) | | target_objects | ["Arm_L", "Body"] | Frame specific objects instead of full scene | | gap_focus_m | 0.002 | Auto-zoom to show a gap of this distance | | display_mode | "MATERIAL" | SOLID, MATERIAL, or WIREFRAME | | action | "SMART_SCREENSHOT" | Automatically picks the best view |

---

Tool Tier System

The AI context window would overflow if all 69 tools were listed in full detail every time. The tier system solves this:

| Tier | Priority | Count | Format in list_all_tools | |------|----------|-------|---------------------------| | ESSENTIAL | 1–9 | 9 | Full detail — title, description, all parameters | | CORE | 10–49 | ~35 | Compact table row | | STANDARD | 50–149 | ~20 | Compact table row | | OPTIONAL | 150+ | 4 | Listed last (external integrations) |

# Filter by intent — reduces 69 tools to ~15 relevant ones (77% fewer tokens)
list_all_tools(intent="rig a character")
list_all_tools(intent="physics simulation")
list_all_tools(intent="export to Unity")

Supports English, Turkish, and French intent keywords.

---

Key Features

Assembly Intelligence

get_scene_graph ANALYZE_ASSEMBLY gives a full integrity report:

• BVH surface-gap measurement — actual vertex-to-face distance, not just bounding-box
• INTERPENETRATION detection — BVH face overlap, not just AABB
• Hierarchy-aware pairs — always tests parent↔child; skips distant objects to avoid O(N²)
• Production readiness score 0–100 — manifold geometry, UV maps, materials, naming, origin alignment

Thread Safety

All bpy calls from the TCP socket thread are automatically marshalled to Blender's main thread via bpy.app.timers. This prevents EXCEPTION_ACCESS_VIOLATION crashes that occur when background threads touch the Blender API.

Multilingual Intent Routing

list_all_tools(intent="...") accepts keywords in English, Turkish, and French. The intent router maps your description to tool categories and returns only the relevant subset — dramatically reducing context window usage.

Visual Verification

get_viewport_screenshot_base64 captures the viewport and returns it as base64 the AI can see:

• Multi-view in one call: FRONT, RIGHT, TOP, ISOMETRIC
• gap_focus_m — zoom precisely to the scale of an assembly gap
• target_objects — frame specific parts, not the whole scene

---

Testing

Tests run without Blender — bpy is mocked with unittest.mock.MagicMock.

uv run pytest tests/unit -q              # 499 unit tests, ~1.4s
uv run pytest tests -v --tb=short        # Full suite
uv run pytest tests -v --cov=blender_mcp # With coverage report
uv run python scripts/quality/run_checks.py --fast   # 8 quality checks
uv run python scripts/quality/run_checks.py          # 12 quality checks

Coverage map — 17 test files

| Module | Test File | Tests | |--------|-----------|-------|

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Immunogenic-prismspectroscope589
• Source: Immunogenic-prismspectroscope589/Blender_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.