blender-ai-mcp

[!WARNING] Project discontinued — this repository is no longer maintained. blender-ai-mcp will not be developed further. It is being replaced by an entirely new and significantly better solution: much stronger 3D scene understanding, deeper and more reliable cooperation with Blender, far better workflow control, and more. The new add-on will be released soon.

A production-shaped MCP server for Blender (archived).

blender-ai-mcp lets Claude, ChatGPT, Codex, and other MCP clients control Blender through a stable tool API instead of ad-hoc Python generation. The result is a safer, smaller, and more reliable surface for real modeling work: goal-first routing, curated public tools, deterministic inspection, and verification that does not depend on guesswork.

Why This Exists

Most "AI + Blender" setups still ask the model to write raw bpy scripts. That breaks exactly where production work gets interesting:

1. Blender APIs drift across versions.
2. Context-sensitive operators fail when the active object, mode, or selection is wrong.
3. Raw scripts give weak feedback when something goes wrong.
4. Vision can describe a result, but it cannot be trusted as the final authority.

blender-ai-mcp takes the opposite approach: treat Blender control as a product surface, not a code-generation stunt.

Why This MCP Server Instead of Raw Python

• Stable contracts over script synthesis. The model calls tools with validated parameters instead of improvising Blender code.
• Goal-first orchestration. Normal guided sessions start from router_set_goal(...), so the system knows what the model is trying to build before it starts calling low-level actions.
• Small public surface. The default llm-guided profile exposes a tiny, search-first bootstrap layer instead of flooding the model with the whole runtime inventory.
• Truth-first verification. Inspection, measurement, and assertion tools determine what is actually true in Blender.
• Safe execution boundaries. The Blender addon executes operations on Blender's main thread while the MCP server handles routing, validation, discovery, and structured responses.

The Product Approach

The business idea formalized in TASK-113 is simple:

• Atomic tools are the implementation substrate. They stay small, precise, and mostly hidden from the normal public surface.
• Macro tools are the preferred LLM-facing layer for meaningful task-sized work.
• Workflow tools are bounded multi-step process tools with explicit reporting, not open-ended "do anything" endpoints.
• Goal-first orchestration keeps sessions anchored to an active intent instead of making the model rediscover context on every turn.
• Vision assists interpretation, while deterministic measurement and assertions provide the final truth layer.
• Pluggable vision runtimes now cover local MLX plus external OpenRouter and Google AI Studio / Gemini provider paths, with model-family-specific external contract profiles for prompt/schema/parser behavior.

This is what turns the project from "Blender tools exposed over MCP" into a usable AI control product for modeling pipelines.

LLM-Guided Public Surface

llm-guided is the default production-oriented surface. It is intentionally small, search-first, and designed around goal-aware sessions.

Normal guided flow: