holdmybeer-gg/blend-ai

128 stars 0 forks Quality 55 Trend 55

The most intuitive and efficient MCP Server for Blender. Control Blender entirely through AI assistants like Claude — create 3D models, set up scenes, animate, render, and more, all through natural...

Overview

README

blend-ai

blend-ai goes beyond tool exposure: it guides the LLM to produce professional 3D results through expert prompts, proven workflows, visual feedback, and mesh quality analysis.

This was created via Claude Code using the Haiku model and 20 random reference images. It took 5 minutes:

Fifteen procedural materials, each built by a single create_procedural_material call. The selected ball’s node graph below was generated entirely by that one call — coordinates, mapping, noise, height mask, colour ramp, and Principled BSDF, laid out and wired:

Key Features

164 tools across 24 modules covering every major Blender domain: modeling, mesh editing, materials, shader nodes, lighting, camera, animation, rendering, sculpting, UV mapping, physics, geometry nodes, rigging, curves, annotations, collections, file I/O, Bool Tool, viewport control, mesh quality analysis, and extension suggestions
12 expert prompts — topology best practices, real-world scale references, lighting principles, studio setup, character basemesh workflow, PBR material guide, auto-critique feedback loop, and more
Visual feedback loop — fast viewport screenshots via OpenGL render (~ms, not seconds) with auto-critique prompts that guide the LLM to check its own work
Mesh quality analysis — structured reports covering non-manifold edges, loose vertices, zero-area faces, duplicate vertices, and wire edges
Extension suggestions — proactively recommends Bool Tool, LoopTools, and Node Wrangler when a task would benefit from them (skips already-installed extensions)
Sandboxed code execution — execute_blender_code blocks dangerous imports (os, subprocess, socket, etc.) and dangerous builtins (exec, eval, open) while allowing safe Blender operations
Render-aware — automatically detects when Blender is rendering and queues commands. Recovers from stuck render guards via load_post handler and reset command
Blender 4.2+ compatible — ships as a Blender Extension; tested against Blender 5.1 with EEVEE identifier, Annotation API, sculpt stroke_method, SLIM UV unwrap, Raycast shader node, and EEVEE light path intensity controls
Custom port — configure the server port from the N-panel UI (default: 9876, range: 1024–65535)
Zero telemetry — no usage tracking, no analytics, no data collection. Everything runs locally on 127.0.0.1
Zero-dependency addon — the Blender addon uses only Python stdlib + bpy. Nothing to pip install inside Blender
Thread-safe architecture — background TCP server with queue-based main-thread execution, TCP keepalive for stale connection detection
1190 tests — comprehensive coverage across tools, handlers, validators, prompts, and the cross-platform installer (ubuntu/macos/windows × py3.11/3.13 in CI)

Quickstart

1. Install the MCP server

git clone https://github.com/HoldMyBeer-gg/blend-ai.git
cd blend-ai
uv pip install -e .

2. Install the Blender addon

Download the latest addon zip from GitHub Releases
Open Blender 4.2 or later
Go to Edit > Preferences > Get Extensions, click the dropdown (▾) top-right, and choose Install from Disk…
Select the downloaded .zip file
Enable “blend-ai” in the extensions list

Blender 4.0 / 4.1 users: Not supported. blend-ai ships as a Blender Extension, which requires Blender 4.2 (LTS) or later. Please upgrade Blender from blender.org/download.

3. Start the server in Blender

In Blender’s 3D Viewport, open the N-panel (press N), find the blend-ai tab. Set your preferred port (default: 9876), then click Start Server.

4. Connect your AI assistant

Expert Guidance

blend-ai includes 12 MCP prompts that guide the LLM toward professional-quality results:

Prompt	What It Teaches
`blender_best_practices`	Bool Tool preference, mesh editing patterns, modifier workflow
`topology_best_practices`	Quad topology, edge flow, poles, n-gon cleanup, face density
`scale_reference_guide`	Real-world dimensions for 8 common objects, unit system setup
`lighting_principles`	Three-point lighting, HDRI, EEVEE vs Cycles, color temperature
`studio_lighting_setup`	6-step studio lighting workflow with specific energy values
`character_basemesh_workflow`	7-step character base mesh from cube with mirror + subdivision
`material_workflow_guide`	PBR materials, Principled BSDF recipes, texture color spaces
`auto_critique_workflow`	Visual feedback loop — when to screenshot, what to check, token budget
`product_shot_setup`	Professional product shot setup guide
`character_base_mesh`	Character modeling guide
`scene_cleanup`	Scene organization workflow
`animation_turntable`	Turntable animation setup

Tool Domains

Architecture

AI Assistant  blend-ai server  Blender addon  Blender

Privacy & Security

Limitations

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests (1190 tests)
uv run --extra dev pytest

# Run tests with coverage
uv run --extra dev pytest --cov=blend_ai

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

License

AGPL-3.0-or-later. See LICENSE.

View this README on GitHub

Install

This server does not publish a one-line install command.

Open the repository installation guide

Configuration

{
  "mcpServers": {
    "blend-ai": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blend-ai", "blend-ai"]
    }
  }
}