Blender MCP Ultra

The ultimate Blender MCP server — 150+ tools, expert prompts, visual feedback, mesh quality analysis, and goal-first routing. Better than paid alternatives.

What This Is

A production-grade Model Context Protocol (MCP) server that gives AI agents complete control of Blender. It combines the best features from all existing Blender MCP projects into a single, modular, well-tested package.

Features

• 150+ structured tools across 24 modules (scene, objects, transforms, modeling, mesh editing, materials, lighting, camera, animation, rendering, viewport, sculpting, UV, physics, geometry nodes, curves, armature, collections, file I/O, procedural generation, code execution)

• 12 expert prompts — topology best practices, real-world scale references, lighting principles, PBR material recipes, character basemesh workflow, product shot setup, auto-critique workflow, undo strategy, animation principles, scene cleanup, render style presets, common operators reference

• Visual feedback loop — fast viewport screenshots via OpenGL with auto-critique prompts that guide the LLM to check its own work

• Mesh quality analysis — non-manifold edges, loose vertices, zero-area faces, duplicate vertices, production readiness score

• Goal-first session management — structured workflow phases (plan → build → inspect → finish)

• Thread-safe architecture — background TCP server with queue-based main-thread execution

• Zero telemetry — everything runs locally on 127.0.0.1

• Blender 4.2+ compatible — ships as a Blender Extension

• Modular addon — 21 handler modules, each covering a specific Blender domain

• Comprehensive validation — all inputs sanitized before reaching Blender

Architecture

AI Agent ←stdio/MCP→ blender-mcp-ultra server ←TCP socket→ Blender addon ←bpy→ Blender

MCP Server (src/blender_mcp_ultra/)

• FastMCP server with tools, prompts, and resources

• TCP client with length-prefixed JSON protocol

• Input validation and security sandboxing

• Session management with goal tracking

Blender Addon (addon/)

• Background TCP socket server on 127.0.0.1:9876

• Command queue drained on Blender's main thread via bpy.app.timers

• 21 handler modules for each Blender domain

• N-panel UI for start/stop and port configuration

• Zero external dependencies — uses only Python stdlib + bpy

Quick Start

1. Install the MCP Server

cd "blender-mcp-ultra"
pip install -e .
# or
uv pip install -e .

2. Install the Blender Addon

1. Open Blender 4.2+

2. Go to Edit > Preferences > Get Extensions

3. Click Install from Disk

4. Select the addon/ directory from this project

5. Enable "Blender MCP Ultra" in the extensions list

6. Click Start MCP Server in the N-panel (View3D > Sidebar > MCP Ultra)

3. Connect Your MCP Client

Add to your MCP client config:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blender-mcp-ultra", "blender-mcp-ultra"]
    }
  }
}

Tool Modules (24)

Expert Prompts (12)

1. Topology Best Practices — quad topology, edge flow, n-gon cleanup

2. Scale Reference Guide — real-world dimensions for characters, architecture, props

3. Lighting Principles — three-point lighting, color temperature, EEVEE vs Cycles

4. Material Workflow Guide — PBR recipes, texture color spaces

5. Auto-Critique Workflow — visual feedback loop for self-assessment

6. Character Basemesh Workflow — step-by-step character creation

7. Product Shot Setup — professional product photography

8. Animation Principles — 12 principles applied to Blender

9. Scene Cleanup — naming conventions, organization, optimization

10. Render Style Presets — photorealistic, toon, product, archviz, pixel art

11. Undo Strategy — managing undo/redo in AI workflows

12. Workflow Orchestration — multi-step 3D workflow planning

What Makes This Better Than Paid Alternatives

Development

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

# Run linter
ruff check src/

# Run tests
pytest tests/

License

MIT — do whatever you want with it.

Credits

Built by analyzing and combining the best ideas from:

• ahujasid/blender-mcp — the original

• HoldMyBeer-gg/blend-ai — 164 tools, expert prompts

• PatrykIti/blender-ai-mcp — goal-first routing