blender-ai-mcp

A production-shaped MCP server for Blender.

`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:

1. `router_set_goal(...)`

2. `browse_workflows`, `search_tools`, or `call_tool`

3. use grouped/public tools such as `check_scene`, `inspect_scene`, or `configure_scene`

4. verify with inspection plus `scene_measure_*` and `scene_assert_*`

Prompting rule:

• use the prompt-library assets in _docs/_PROMPTS/README.md as the canonical guided operating instructions
• when a client drifts, prepend `guided_session_start` as the generic search-first stabilizer
• if a tool is not already directly visible on the current surface/phase, use `search_tools(...)` before `call_tool(...)`

When a bounded modeling intent matches, the default public working layer should be the macro layer:

• `macro_cutout_recess` for recesses, openings, and cutter-driven cutouts
• `macro_relative_layout` for align/place/contact-gap part layout
• `macro_attach_part_to_surface` for seating one part onto another object's surface/body
• `macro_align_part_with_contact` for minimal repair nudges on pairs that almost fit
• `macro_place_symmetry_pair` for mirrored pair placement/correction around an explicit mirror plane
• `macro_place_supported_pair` for mirrored pair placement/correction against one shared support surface
• `macro_cleanup_part_intersections` for bounded pairwise overlap cleanup without free-form collision solving
• `macro_adjust_relative_proportion` for bounded ratio repair between related objects
• `macro_adjust_segment_chain_arc` for bounded arc adjustment on ordered segment chains
• `macro_finish_form` for preset-driven bevel/subdivision/solidify finishing
• `reference_images` for goal-scoped reference intake before bounded visual comparison
• `reference_guided_creature_build` as a native prompt asset for staged generic creature work on `llm-guided`
• `recommended_prompts` can now steer creature-oriented guided sessions toward that prompt path by using active goal/session context
• `guided_reference_readiness` on `router_set_goal`, `router_get_status`, and staged reference compare/iterate payloads so clients can see whether reference-driven stage work is actually ready
• `reference_compare_stage_checkpoint` for deterministic multi-view stage comparison against attached references during manual iterative work
• `reference_iterate_stage_checkpoint` for a session-aware staged correction loop that remembers prior focus, can escalate into inspect/validate when the same correction repeats, and can now target one object, many objects, a collection, or the full assembled silhouette
• stage compare/iterate now also expose deterministic `silhouette_analysis` metrics, typed `action_hints`, and an advisory-only `part_segmentation` placeholder that stays disabled unless a separate sidecar is explicitly enabled
• `scene_scope_graph` for one explicit read-only structural scope artifact with anchor/core/accessory role hints
• `scene_relation_graph` for one explicit read-only pair-relation artifact derived from the current truth layer
• `scene_view_diagnostics` for one explicit read-only view-space artifact with projected extent, frame coverage, centering, and visible/partial/occluded/off-frame verdicts for named cameras or `USER_PERSPECTIVE`
• those spatial graph/view diagnostics tools are now part of the default visible `llm-guided` support set so the model can keep one explicit 3D orientation layer available instead of inferring spatial state only from names, screenshots, or partial loop payloads

Current guided bootstrap surface:

• `router_set_goal`
• `router_get_status`
• `browse_workflows`
• `reference_images`
• `scene_scope_graph`
• `scene_relation_graph`
• `scene_view_diagnostics`
• `search_tools`
• `call_tool`
• optional prompt bridge tools when `MCP_PROMPTS_AS_TOOLS_ENABLED=true`:
  • `list_prompts`
  • `get_prompt`

Prompt-capable clients should prefer native MCP prompts. The prompt bridge is a

compatibility layer for tool-only clients and can be disabled for Streamable HTTP

profiles that already consume native prompt components.

Current guided utility prep path:

• bootstrap/planning search can now reach:
  • `scene_get_viewport`
  • `scene_clean_scene`
• these utility actions stay bounded and do not reopen the full legacy surface
• the canonical guided discovery wrapper is `call_tool(name=..., arguments=...)`
• the canonical cleanup argument shape on `llm-guided` is

`keep_lights_and_cameras`; older split flags are compatibility-only and

should not be used as the documented public form

• `reference_images(action="attach", source_path=...)` is one-reference-per-call;

batch-like shapes now fail with guided recovery guidance instead of raw schema noise

• `collection_manage(action=..., collection_name=...)` stays the canonical

public form; legacy `name` is only a narrow compatibility alias

• `modeling_create_primitive(...)` stays limited to `primitive_type`,

`radius`/`size`, `location`, `rotation`, and optional `name`; unsupported

shortcuts such as `scale`, `segments`, `rings`, `subdivisions`, or

primitive-time `collection_name` now fail with actionable guidance on both

direct and proxy guided paths

• build goals should still start from `router_set_goal(...)`, but screenshot /

viewport / scene-reset requests should use the guided utility path instead

• if stale scene state is discovered only after entering the guided build

surface, `scene_clean_scene(...)` is also available there as a bounded

recovery hatch; cleanup before the goal is still the preferred path

• build-phase cleanup is still allowed when recovery is needed

Current public aliases on `llm-guided`:

Why that matters:

• the guided profile starts from a compact visible bootstrap set instead of the

full catalog

• grouped/public tools stay easy to discover
• hidden atomic tools remain available as infrastructure, not as the default public mental model
• specialist families stay out of the normal guided entry layer until the macro surface is broader

Atomic Foundations And Docs

The root `README.md` is intentionally not the full tool catalog anymore.

The detailed tool inventory and atomic family docs should stay in docs, not on the front page. That is the right long-term structure after `TASK-113`.

Use these docs depending on what you need:

• Tool Layering Policy
  • Canonical policy for `atomic / macro / workflow`, hidden atomic tools, goal-first usage, and vision/assert boundaries.
• MCP Server Docs
  • Surface profiles, guided aliases, versioned contracts, and runtime/platform guidance.
• MCP Client Config Examples
  • Ready-to-paste local MCP client config examples for guided/manual surfaces plus MLX, OpenRouter, and Gemini vision variants.
• Vision Layer Docs
  • Runtime/backends, capture bundles, reference images, macro/workflow vision integration notes, and repo-tracked real viewport eval bundles for both direct user-view and fixed camera-perspective captures.
• LLM Guide v2
  • Strategy doc for a typed spatial-intelligence layer, compact relation state, and bounded next-step handoffs for guided operation.
• Spatial Intelligence Research Brief
  • External research handoff for LLM/VLM spatial reasoning, multi-view reasoning, and geometry-aware planning.
• Spatial Intelligence Upgrade Proposal
  • Research-driven upgrade proposal for scene graphs, symbolic relation notation, and supporting geometry-library choices.
• Available Tools Summary
  • Full inventory and grouped/public tool overview.
• Tool Architecture Index
  • Maintainer-facing map of the tool families underneath the MCP surface.

If you want to see the atomic families the server is built on, start here:

• Scene Tool Architecture
• Modeling Tool Architecture
• Mesh Tool Architecture
• Mega Tool Architecture

Recommended interpretation:

• keep `/_docs/TOOLS/` as the maintainer-facing atomic/grouped architecture map
• keep `README.md` product-facing and compact
• keep `/_docs/AVAILABLE_TOOLS_SUMMARY.md` as the runtime inventory

Provider Notes

Current short version:

• Local default: `mlx_local` with a Qwen VL 4B-class model path; current repo-validated baseline is `mlx-community/Qwen3-VL-4B-Instruct-4bit`
• External iterative compare candidate: OpenRouter with `x-ai/grok-4.20-multi-agent`
• External Google-family compare path: OpenRouter-hosted Google-family models plus Google AI Studio / Gemini now share the same narrow staged-compare contract through resolved `vision_contract_profile` routing

External vision runtime note:

• `VISION_EXTERNAL_PROVIDER` selects the transport/provider branch
• `VISION_EXTERNAL_CONTRACT_PROFILE` optionally overrides the prompt/schema/parser contract for external compare flows
• when the override is unset, the runtime auto-matches Google-family model ids such as `gemma` / `gemini` / `learnlm`, then falls back to provider defaults

Detailed per-provider table:

• Vision Layer Docs -> Provider Notes

Architecture

The system is split on purpose:

• MCP server (`server/`): FastMCP surface, public tool definitions, transforms, discovery, and response contracts.
• Router (`server/router/`): goal interpretation, safety/correction policy, workflow matching, session context, and guided execution behavior.
• Blender addon (`blender_addon/`): actual `bpy` execution, RPC handlers, and Blender main-thread-safe operation scheduling.

Communication happens through JSON-RPC over TCP sockets.

More detail:

• ARCHITECTURE.md
• Router Docs
• Runtime Responsibility Boundaries
• Addon Docs

Structured Contract Baseline

The server is moving critical surfaces toward machine-readable payloads instead of prose-heavy JSON strings.

Current structured-contract baseline includes:

• `macro_cutout_recess`
• `macro_finish_form`
• `macro_attach_part_to_surface`
• `macro_align_part_with_contact`
• `macro_place_supported_pair`
• `macro_cleanup_part_intersections`
• `macro_relative_layout`
• `scene_create`
• `scene_configure`
• `mesh_select`
• `mesh_select_targeted`
• `mesh_inspect`
• `scene_snapshot_state`
• `scene_compare_snapshot`
• `scene_measure_distance`
• `scene_measure_dimensions`
• `scene_measure_gap`
• `scene_measure_alignment`
• `scene_measure_overlap`
• `scene_assert_contact`
• `scene_assert_dimensions`
• `scene_assert_containment`
• `scene_assert_symmetry`
• `scene_assert_proportion`
• `router_set_goal`
• `router_get_status`
• `workflow_catalog`

That is important for automation, auditing, and future macro/workflow composition.

Contact Truth Semantics

For contact-sensitive checks on curved or rounded forms, the truth layer now

distinguishes:

• mesh-surface contact/gap semantics when a bounded mesh-aware path is

available

• bbox fallback semantics when a mesh-aware path is not available

That means a pair can still show bbox contact while the main measured relation

remains `separated` if the real mesh surfaces still have a visible gap. Guided

hybrid truth follow-up now carries that distinction forward in operator-facing

summaries instead of collapsing it into a generic "contact passed/failed"

claim.

When the mesh-aware path finds a real overlap, the main measured relation also

stays `overlapping`, so overlap rejection in `scene_assert_contact(...)` still

works as a separate truth condition instead of collapsing into plain contact.

Structured Clarification Flow

The guided surface supports missing-input handling as part of the product contract, not as an afterthought.

• Model-first clarification is the default for `router_set_goal(...)` on `llm-guided`: missing workflow parameters return a typed `needs_input` payload to the outer model first.
• Typed fallback payloads keep the same flow usable on tool-only or compatibility clients.
• Human/native clarification is reserved for later/fallback policy rather than the default first step of workflow execution.
• `router_set_goal(...)` can ask for constrained choices, booleans, enums, or workflow confirmation.
• `partial answers` survive across follow-up turns.
• `workflow_catalog` import conflicts reuse the same clarification model.

Guided Handoff Contract

The guided surface now treats workflow fallback as an explicit typed contract instead of a phase side effect hidden in prose.

• `router_set_goal(...)` returns `guided_handoff` on bounded continuation paths such as `continuation_mode="guided_manual_build"` and `continuation_mode="guided_utility"`.
• `guided_handoff` names the `target_phase`, `direct_tools`, `supporting_tools`, and `discovery_tools` for the next step on `llm-guided`.
• `workflow_import_recommended` stays `False` on these fallback paths unless the user explicitly asks for workflow import/create behavior.
• `router_get_status(...)` preserves the active `guided_handoff` in session diagnostics so clients can recover the intended continuation path.

Server-Driven Guided Flow State

The guided surface now carries one explicit machine-readable `guided_flow_state`

contract in addition to `guided_handoff`.

• `router_set_goal(...)`, `router_get_status(...)`,

`reference_compare_stage_checkpoint(...)`, and

`reference_iterate_stage_checkpoint(...)` can expose `guided_flow_state`

for the active `llm-guided` session

• `guided_flow_state` reports:
  • `flow_id`
  • `domain_profile`
  • `current_step`
  • `completed_steps`
  • `active_target_scope`
  • `spatial_scope_fingerprint`
  • `spatial_state_version`
  • `spatial_state_stale`
  • `last_spatial_check_version`
  • `spatial_refresh_required`
  • `required_checks`
  • `next_actions`
  • `blocked_families`
  • `allowed_families`
  • `allowed_roles`
  • `completed_roles`
  • `missing_roles`
  • `required_role_groups`
  • `required_prompts`
  • `preferred_prompts`
  • `step_status`
• current domain overlays are:
  • `generic`
  • `creature`
  • `building`
• early guided build sessions now start from a step-gated spatial-context

phase instead of exposing the whole build surface immediately

• `scene_scope_graph(...)` binds the active guided target scope when no active

scope exists yet; spatial refresh checks must keep using that already-bound

target scope instead of rebinding to a different object set

• unrelated view checks such as

`scene_view_diagnostics(target_object="Camera", ...)` do not satisfy a

creature/building spatial check by themselves

• if reference images are attached for the active guided goal, treat them as

the primary grounding input before deciding the first body/head/tail masses

and rough silhouette

• use full semantic object names such as `Body`, `Head`, `Tail`,

`ForeLeg_L`, and `HindLeg_R` instead of opaque abbreviations like `ForeL`

/ `HindR`, because guided seam/role heuristics are more reliable on readable

names

• on `llm-guided`, the server can now warn on weak role-sensitive names and

block clearly opaque placeholder names such as `Sphere` / `Object` when they

are used as semantic part names

• do not call `scene_scope_graph(...)`, `scene_relation_graph(...)`, or

`scene_view_diagnostics(...)` with no explicit scope and assume that means

“inspect the whole scene”

• during an active guided spatial gate or spatial refresh re-arm, all three of

those spatial helpers should be treated as explicit-scope tools, not as

whole-scene probes

• those pinned read-only spatial helpers remain callable while visible on

`llm-guided`; guided family blocking must not reject

`scene_scope_graph(...)`, `scene_relation_graph(...)`, or

`scene_view_diagnostics(...)` simply because the current build step's

`allowed_families` omits `spatial_context`

• outside that guided gate, the scope/relation graph builders still require an

explicit `target_object`, `target_objects`, or `collection_name`; a bare

call now fails instead of silently returning an empty `scene` scope

• default placeholder scopes such as a stock `Cube` or the generic root

`Collection` are no longer treated as meaningful guided target/workset

bindings by themselves

• but for the earlier “is this scene already non-empty?” bootstrap decision,

Blender's stock `Cube` plus stock camera/light helpers still enters the

empty-scene primary-workset bootstrap path

• this non-empty decision is intentionally name-light after startup: real

multi-object rough blockouts with default primitive names such as `Cube` or

`Sphere` still count as existing geometry, while helper-only scenes can still

enter `bootstrap_primary_workset`

• explicit guided scopes now bind from caller intent instead of name

heuristics, so real objects named like `Cube`, `Sphere`, or `Sunflower`

can still become the active guided workset when the operator targets them

• after material scene changes such as `scene_clean_scene(...)`,

`scene_duplicate_object(...)`, `scene_rename_object(...)`,

`modeling_create_primitive(...)`, `modeling_transform_object(...)`,

`modeling_join_objects(...)`, `modeling_separate_object(...)`, or bounded

attachment/alignment macros, the guided runtime can mark the spatial layer

stale and re-arm the required checks

• that same dirty-state update now reapplies FastMCP visibility immediately,

so clients see the required spatial support tools as soon as

`spatial_refresh_required` is persisted

• on Streamable HTTP, guided dirty-state and visibility finalizers must complete

before the active tool response returns; routed sync tools that mutate scene

state defer those finalizers to the MCP async wrapper instead of scheduling

detached session-state writes

• async wrappers and native async modeling helpers keep the blocking

sync router/RPC execution on a worker thread; only the guided finalizers run

back on the event loop before the Streamable HTTP response completes

• async dirty macro helpers such as `macro_cutout_recess(...)` and

`macro_finish_form(...)` use the awaited async route path so visibility is

reapplied before the Streamable HTTP response completes

• async spatial helpers such as `scene_scope_graph(...)`,

`scene_relation_graph(...)`, and `scene_view_diagnostics(...)` route their

Blender-backed graph/diagnostic reads off the event loop before recording

guided spatial-check completion

• async guided identity finalizers such as successful `scene_rename_object(...)`

validation also keep Blender-backed scene lookups off the event loop before

updating the guided part registry

• native async modeling tools that consume a router execution report must still

surface `guided_naming` warnings through the active MCP context; otherwise

weak semantic names can lose their model-facing correction hints on

Streamable HTTP

• native async modeling and cleanup finalizers derive successful scene

mutations from structured `report.steps`, not the rendered legacy route text;

multi-step corrected routes prefix legacy lines and are not a reliable source

for guided dirty-state or role-registration decisions

• async guided-role registration reapplies FastMCP visibility after the final

advanced `guided_flow_state` is persisted, so `list_tools()` reflects the

new guided step before the Streamable HTTP response completes

• async public tool variants must preserve the original public docstrings,

especially for visible guided spatial and modeling helpers whose descriptions

teach required scope arguments, workflow order, and argument constraints

• when the router corrects a successful `modeling_transform_object(...)` call

to another valid object name, guided spatial dirty-state and guided-role

follow-up use the transformed object name returned by the final modeling

step, not the original caller-supplied name

• guided mesh edit tools such as `mesh_extrude_region(...)`,

`mesh_loop_cut(...)`, and `mesh_bevel(...)` are now mapped to the

`secondary_parts` family, so they are blocked during spatial-context gates

and re-arm spatial checks after successful geometry edits

• when one of those required spatial checks completes and advances the guided

flow, the server now reapplies FastMCP visibility immediately instead of

waiting for a later status/search refresh

• support/symmetry-aware relation pairs now preserve support and symmetry

annotations even when they share the same `(from_object, to_object)` key as a

generic primary-target pair, so later guided planners still see

support/symmetry semantics instead of only a generic edge

• relation graphs that include required creature seams still add fallback

`primary_to_other` pairs for non-seam objects in the requested scope, so

unclassified objects do not disappear from mixed guided diagnostics

• healthy support/symmetry pairs no longer count as failing just because their

centers differ or they are not literal contact pairs; only `unsupported` /

`asymmetric` support/symmetry verdicts count as failures there

• when `guided_flow_state.spatial_refresh_required == true`, treat

`next_actions=["refresh_spatial_context"]` as authoritative server state,

not advisory prose; refresh with `scene_scope_graph(...)` against the

already-bound target scope first, then rerun the remaining required spatial

checks on that same scope

• `scene_view_diagnostics(...)` only counts toward the guided spatial gate when

it returns real available view-space evidence; a headless/unavailable probe

stays read-only and does not satisfy the required check by itself

• if stage compare/iterate finds important issues while the current guided

role/workset slice is still incomplete, the governor can now keep the session

in bounded build continuation instead of escalating too early into

`inspect_validate`

• when that incomplete-stage hold returns

`loop_disposition="continue_build"`, the persisted `guided_flow_state`

remains on the same current step and does not mark the unfinished role slice

as completed; keep following `missing_roles` before relying on later-stage

visibility

• this incomplete-stage hold also applies when stage iterate has no

`correction_focus` or `action_hints`; a no-action compare result must not

advance a guided build with required missing roles to `finish_or_stop`

• after the flow reaches a later step such as `place_secondary_parts`, the

server can still keep missing primary masses available when they are part of

the same bounded workset, instead of forcing a squirrel/building run to

abandon an unfinished core mass immediately

• for creature blockout seams, `intersecting` can still be acceptable for

embedded ear/head or snout/head placement, but `floating_gap` on head/body,

tail/body, or limb/body remains actionable

• if a needed tool family is hidden/blocked-by-flow, inspect

`router_get_status().guided_flow_state`, complete the listed

`required_checks`, and follow `next_actions` instead of guessing hidden tool

names into `call_tool(...)`

• if an explicit guided goal stayed on a manual/no-match path, a strong

pattern-suggested workflow can still expand; what remains suppressed in that

state is the lower-confidence heuristic reopening path

• exact tool-name searches on the guided surface are now shaped to return a

tighter, smaller result set instead of flooding the model with a full

expanded payload for simple lookups

• for role-sensitive build steps, treat `allowed_roles` and `missing_roles` as

part of the execution contract, not as advisory prose

• housekeeping/workset operations such as `collection_manage(...)` should stay

available for already-created objects even when their semantic role was

registered in an earlier step

• bounded refinement of an already-registered primary object can remain

possible after the session moves into the next step; later steps are not

meant to freeze all earlier masses completely

• use `guided_register_part(object_name=..., role=...)` as the canonical

way to tell the server what semantic part one object represents; optional

`guided_role=...` hints on build tools are convenience-only

• optional `role_group=...` values must match the server's domain role map;

callers cannot reclassify `body_core`, `head_mass`, or similar

role-sensitive mutating calls as `utility` or another family to bypass the

current guided phase gate

• `guided_register_part(...)` now validates that the named Blender object

actually exists before it can count toward guided role completion; typos do

not create completed roles on their own

• if guided object validation cannot read the Blender scene at all,

`guided_register_part(...)` now fails clearly instead of mutating guided

session state from an unverified object name

• explicit target names passed into `scene_scope_graph(...)` / scope-building

paths now follow the same Blender-truth validation rule before the guided

scope can bind

• those optional `guided_role=...` hints only auto-register when an active

guided flow already exists; outside an active guided flow they do not create

persistent role state by themselves

• a failed create call now stays non-mutating for guided role state as well:

if `modeling_create_primitive(...)` returns a failure string, the requested

role is not auto-registered just because a semantic `name` was supplied

• on `modeling_create_primitive(...)`, `guided_role=...` now also requires an

explicit semantic `name`; guided create does not allow auto-generated Blender

names to become semantic part registrations

• when the router prepends corrective steps such as `scene_set_mode(...)`,

successful guided create/transform calls still register the resulting role

against the final modeling step instead of dropping the convenience

registration just because the call became multi-step

• guided-role convenience registration now also handles valid object names

containing apostrophes, such as `King's Crown`, instead of truncating the

stored object name

• guided runtime success parsing also treats apostrophes inside quoted object

names as part of the object name for create/transform/rename/join results,

so stale-state marking and guided registry sync still run after successful

mutations

• canonical pair names such as `ForeLeg_L`, `ForeLeg_R`, and `ForeLegPair`

now count as strong semantic names for `foreleg_pair` / `hindleg_pair`

instead of warning or blocking under the stricter naming policy

• on `modeling_create_primitive(...)`, guided-role auto-registration now binds

to the actual created object name returned by Blender, so role state stays

aligned even when Blender auto-numbers a default name such as `Cube.001` or

uses a different default object name such as `Suzanne`

• on `modeling_transform_object(...)`, guided-role auto-registration now binds

to the actual transformed object name returned by the final routed step, so

router-corrected object identity still re-arms spatial checks and updates

role state for the object that really changed

• successful `scene_rename_object(...)` calls now keep the guided part registry

aligned with the renamed Blender object, so later role-sensitive transforms

still recover the registered role without manual re-registration

• successful `scene_rename_object(...)` calls also re-arm guided spatial

checks, because the bound target-scope fingerprint is name-based

• successful `scene_duplicate_object(...)` calls also re-arm guided spatial

checks, because duplication changes the visible workset/scope relation facts

• failed plain-string mutation results such as `Object 'Missing' not found`

now stay non-mutating for guided session state; they do not re-arm spatial

checks or rewrite guided role registration just because the wrapper returned

a string

• `scene_clean_scene(...)` now clears the guided part registry and returns the

guided flow to `bootstrap_primary_workset` instead of carrying completed

parts forward on an empty scene

• starting a different guided goal in the same session now resets guided part

registration for that new flow instead of carrying completed roles forward

from the previous object

• destructive identity/topology changes such as `modeling_join_objects(...)`

or `modeling_separate_object(...)` now drop stale guided part registrations;

re-register the resulting object(s) explicitly if they should still count

toward guided role completion

• those same destructive topology changes also re-arm guided spatial checks,

because previously captured scope/view facts are no longer trustworthy after

objects were merged away or split apart

• for macro capture/vision artifacts, `macro_attach_part_to_surface(...)` now

refreshes its post-action capture bundle after the extra mesh-surface nudge,

so attached images and truth summary describe the final seated pose instead

of the pre-nudge intermediate pose

• routed macro reports can be `partial` and still carry an `error`; MCP

adapters preserve that structured report, including `actions_taken`,

modified objects, verification recommendations, capture/truth data, and

follow-up guidance, instead of coercing it into an empty failed envelope

• if the optional segmentation sidecar is enabled on runtime config but not yet

executed on the current compare path, staged compare/iterate responses now

report `part_segmentation.status="unavailable"` instead of silently staying

`disabled`

• if the server warns or blocks on guided naming, rename or create the object

using one of the suggested semantic names instead of retrying the same weak

abbreviation

• guided naming and guided spatial role inference now use token-boundary style

matches instead of raw substring hits, so names such as `Heart` or

`TruthBodyAnchorHead` do not become accidental semantic ear/body/head roles

• the `required prompt bundle` and `preferred prompt bundle` named in

`guided_flow_state` are prompt asset names, not a replacement for the

server-driven flow; prompts support the flow, they do not become the flow

Guided Reference Readiness

Reference-driven staged work now has one explicit readiness contract instead of

hidden ordering assumptions.

• `router_set_goal(...)` and `router_get_status(...)` expose `guided_reference_readiness`.
• the payload reports `attached_reference_count`, `pending_reference_count`,

`compare_ready`, `iterate_ready`, plus machine-readable `blocking_reason` and

`next_action`

• `reference_images(action="attach", source_path=...)` can stay pending until the guided

goal session is actually ready, then adopt automatically

• if the same goal already has active refs and new ones are staged during

`needs_input`, the staged refs stay separate from the already-active goal

references until readiness returns

• if a ready session still carries explicit pending refs for another goal,

`reference_images(action="list"| "remove"| "clear", ...)` now treats that

merged visible set consistently instead of leaving broken pending records

• `reference_compare_stage_checkpoint(...)` and

`reference_iterate_stage_checkpoint(...)` now fail fast when the session is

not ready, and echo the same `guided_reference_readiness` payload

• if `reference_iterate_stage_checkpoint(...)` returns

`loop_disposition="inspect_validate"`, stop free-form modeling and switch to

inspect/measure/assert immediately

• if it returns `loop_disposition="continue_build"` while

`guided_flow_state.missing_roles` is still non-empty, continue the current

role slice; the server intentionally keeps the guided step in place instead

of advancing to the next stage, even when the compare result itself produced

no actionable correction hints

• `router_set_goal(..., gate_proposal={...})` may accept an optional model- or

reference-derived gate proposal for the active guided goal. The server

normalizes it into `active_gate_plan`, starts every gate as `pending`, and

returns `gate_intake_result.policy_warnings` for dropped hidden tool names,

unsupported gate types, raw Blender/Python instructions, unavailable required

reference/perception evidence on the goal-time intake surface, or

client-supplied completion claims such as `passed`.

• `router_get_status(...)`, `router_set_goal(...)`, and staged

reference compare/iterate payloads can expose `active_gate_plan`; LLM,

`reference_understanding`, silhouette, segmentation, classification, and VLM

checkpoint sources may propose or support gates, but scene/spatial/mesh and

assertion evidence remain the truth authority for pass/fail status.

• staged reference compare/iterate payloads also project the active gate plan

into top-level `gate_statuses`, `completion_blockers`,

`next_gate_actions`, and `recommended_bounded_tools`, so clients do not need

to infer the immediate repair path from the nested plan shape.

• `scene_relation_graph(...)` updates the first deterministic gate slice for

`required_part`, `attachment_seam`, `support_contact`, and `symmetry_pair`

with authoritative evidence refs, status reasons, completion blockers, and

bounded repair-tool hints; later guided scene mutations mark the affected

verifier-backed statuses `stale` through the existing spatial dirtying path.

• active gate blockers narrow guided visibility/search toward existing

verifier and repair tools; a failed seam gate should lead to relation

graph/measure/assert/macro repair tools, not a broad catalog or goal reset.

• unresolved `completion_blockers` on staged iterate responses now also push

`loop_disposition="inspect_validate"` even when the compare loop did not

repeat the same vision-only correction focus.

• if staged compare degrades but strong deterministic truth findings still

exist, use the same inspect/measure/assert handoff instead of improvising

another large free-form correction

• error-stage iterate handoffs that move to `inspect_validate` or

`finish_or_stop` also reapply guided visibility before returning

• for staged compare/iterate, `goal_override` is no longer a session

substitute; use an active guided goal session instead

• for collection or multi-object staged captures, the capture focus now falls

back to the assembled target scope's primary target when no explicit

`target_object` is supplied

• deterministic silhouette metrics prefer the target/focus capture for the

requested `target_view`, not the broad `context_wide` capture

• `reference_compare_current_view(..., persist_view=True, view_name=...,

orbit_horizontal=..., zoom_factor=...)` keeps the captured user view and does

not replay those same view adjustments a second time during compact view

diagnostics

Session Diagnostics

Guided/runtime payloads now expose explicit MCP session metadata:

• `router_set_goal(...)` includes `session_id` and `transport`
• `router_get_status(...)` includes `session_id` and `transport`
• `reference_compare_stage_checkpoint(...)` includes `session_id` and `transport`
• `reference_iterate_stage_checkpoint(...)` includes `session_id` and `transport`

Current runtime guidance:

• stateful `streamable` HTTP is the recommended transport for longer guided

runs and for debugging session-aware reference / checkpoint flows

• recent guided-session hardening removed the known router bookkeeping path

that could clobber active goal/reference session state during routed tool

execution

• if you investigate a future state-loss incident, compare `session_id` and

`transport` first to distinguish:

Server-Side Sampling Assistants Baseline

The MCP server now has a bounded analytical assistant layer inside an active request.

Current use cases:

• optional `assistant_summary` on inspection-heavy paths such as `scene_snapshot_state`, `scene_compare_snapshot`, `scene_get_hierarchy`, `scene_get_bounding_box`, and `scene_get_origin_info`
• bounded `repair_suggestion` on `router_set_goal`, `router_get_status`, and `workflow_catalog`

Explicit assistant terminal states:

• `success`
• `unavailable`
• `masked_error`
• `rejected_by_policy`

The rule is strict: assistants may help summarize or suggest, but they do not override scene truth or router policy.

Versioned Surface Baseline

Public surface evolution is versioned explicitly:

Compatibility note:

• `llm-guided-v1` remains selectable as a rollback line
• `workflow_catalog`, `scene_context`, and `scene_inspect` participate in the guided surface evolution story

Code Mode Decision

Current benchmark baselines:

• `legacy-flat`
• `llm-guided`
• `code-mode-pilot`

Current decision:

• Go decision: keep `code-mode-pilot` as an experimental read-only surface
• Do not make Code Mode the default path for write-heavy or geometry-destructive Blender work

Support Matrix

• Blender: tested on Blender 5.0 in E2E coverage; addon minimum remains Blender 4.0+ on a best-effort basis.
• Python: 3.11+
• FastMCP task runtime: fastmcp 3.2.4 + pydocket 0.19.x
• Code Mode sandbox extra: pydantic-monty 0.0.11
• OS: macOS / Windows / Linux
• Memory: router semantic features rely on a local LaBSE model and related vector infrastructure

Quick Start

1. Install the Blender addon

1. Download `blender_ai_mcp.zip` from the Releases page or build it locally with `python scripts/build_addon.py`.

2. Open Blender -> Edit -> Preferences -> Add-ons.

3. Click Install... and select the zip file.

4. Enable the addon. It starts the local Blender RPC server on port `8765`.

2. Run the MCP server on the guided profile

Recommended defaults:

• `ROUTER_ENABLED=true`
• `MCP_SURFACE_PROFILE=llm-guided`
• map `/tmp` if you want host-visible image/file outputs

Example Docker command:

docker run -i --rm \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

docker run --rm \
  -p 8000:8000 \
  -v /tmp:/tmp \
  -e BLENDER_AI_TMP_INTERNAL_DIR=/tmp \
  -e BLENDER_AI_TMP_EXTERNAL_DIR=/tmp \
  -e ROUTER_ENABLED=true \
  -e MCP_SURFACE_PROFILE=llm-guided \
  -e MCP_TRANSPORT_MODE=streamable \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_PORT=8000 \
  -e MCP_STREAMABLE_HTTP_PATH=/mcp \
  -e MCP_PROMPTS_AS_TOOLS_ENABLED=false \
  -e BLENDER_RPC_HOST=host.docker.internal \
  ghcr.io/patrykiti/blender-ai-mcp:latest

Example generic MCP client config:

{
  "mcpServers": {
    "blender-ai-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/tmp:/tmp",
        "-e", "BLENDER_AI_TMP_INTERNAL_DIR=/tmp",
        "-e", "BLENDER_AI_TMP_EXTERNAL_DIR=/tmp",
        "-e", "ROUTER_ENABLED=true",
        "-e", "MCP_SURFACE_PROFILE=llm-guided",
        "-e", "BLENDER_RPC_HOST=host.docker.internal",
        "ghcr.io/patrykiti/blender-ai-mcp:latest"
      ]
    }
  }
}

Network notes:

• macOS / Windows: use `host.docker.internal`
• Linux: prefer `--network host` with `BLENDER_RPC_HOST=127.0.0.1`
• `MCP_TRANSPORT_MODE=stdio` keeps the current subprocess/stdio MCP mode
• `MCP_TRANSPORT_MODE=streamable` starts a stateful Streamable HTTP MCP server
• `MCP_PROMPTS_AS_TOOLS_ENABLED=false` disables the tool-compatible prompt bridge

for prompt-capable clients; native MCP prompts remain available

For broader profile/config examples, use:

• MCP Server Docs
• MCP Client Config Examples
• `.env.example` for the full tracked runtime/config variable set

Testing

Unit tests:

PYTHONPATH=. poetry run pytest tests/unit/ -v

Unit collection count:

poetry run pytest tests/unit --collect-only

E2E tests:

python3 scripts/run_e2e_tests.py

E2E collection count:

poetry run pytest tests/e2e --collect-only

Pre-commit:

poetry run pre-commit install --hook-type pre-commit --hook-type pre-push
poetry run pre-commit run --all-files

More detail:

• Test Docs
• Development Docs

Documentation Map

• Architecture
• MCP Server Docs
• Vision Layer Docs
• Router Docs
• Router Responsibility Boundaries
• Addon Docs
• LLM Guide v2
• Spatial Intelligence Research Brief
• Spatial Intelligence Upgrade Proposal
• Available Tools Summary
• Tool Architecture Index
• Prompts
• Tasks

Contributing

Read CONTRIBUTING.md before opening a PR. The repo enforces Clean Architecture boundaries, typed Python, router metadata rules, and pre-commit validation.

Community And Support

If `blender-ai-mcp` is useful in your workflow, consider sponsoring its long-term development.

Sponsorship helps fund maintenance, docs, testing, and the higher-level reliability work that makes this repo different from raw Blender code generation: goal-first routing, curated tools, deterministic verification, and production-shaped workflow support.

Become a sponsor

• SUPPORT.md
• SECURITY.md
• CODE_OF_CONDUCT.md
• GitHub Sponsors
• Buy me a coffee

Author

Patryk Ciechański

• GitHub: PatrykIti

License

This project is licensed under the Apache License 2.0.

See:

• LICENSE.md
• NOTICE