blender-mcp-integration

---
name: blender-mcp-integration
description: Choose, configure, and use Blender MCP integrations for live scene control or deterministic asset evaluation. Use when connecting Codex or Claude Code to an open Blender instance, deciding between Blender Lab MCP and community Blender MCP servers, troubleshooting Blender MCP connectivity, or evaluating whether MCP tools improve a Blender modeling workflow.
---

# Blender MCP Integration

Read [the shared execution guidance](references/astra-workflow.md) once per task
for autonomous decisions, evidence cadence, and long-task continuity.

Use the narrowest MCP layer that improves the task.

## Choose the layer

When the task needs a live viewport, check for a connected Blender session.
If none is available, offer to open Blender and ask the user before launching
it, unless they have already authorized opening it in the current conversation.
After authorization, open a separate session with the requested asset, connect
Agent Studio Live, and retry `blender_open_viewport`. Preserve existing Blender
sessions and unsaved work; a missing connection is a setup step, not a reason
to abandon the viewport handoff.

For an inline viewport, use the bundled **Agent Studio Live** addon and
`blender_open_viewport`. It supports refresh, axis/orbit/zoom navigation and
clicking a surface or object-list entry to attach exact scene context to the
user's next message. Install `addon/blender_agent_studio_live.py` from the
plugin root in Blender, enable it, and press **Connect Agent Studio** in the
3D View sidebar. It requires an interactive Blender session and GPU context;
the ordinary file tools remain independent. See the
[live viewport guide](https://github.com/ifBars/blender-agent-studio/blob/main/docs/live-viewport.md).
The bridge does not execute arbitrary Python or mutate geometry. General live
authoring can still use a separate integration as described below.

1. Use the bundled tools and Blender CLI for ordinary scripted builds, inspection, and rendering. Add Blender's official Lab MCP only when the task needs live interaction with an open Blender session on a supported version.
2. Use Blender Agent Studio's MCP for deterministic batch inspection, standardized geometry evidence, and bounded authored-scene renders. `blender_render_scene` preserves cameras, lights, volumes and color management and returns the first image inline; `inspectOnly` discovers scene settings before rendering. The bundled Poly Haven search/download tools also acquire verified CC0 textures and HDRIs without another add-on or API key; see the rendering workflow for material setup and standalone CLI use.
3. Consider `ahujasid/blender-mcp` only when the request needs its additional remote-host, Poly Haven, Sketchfab, or external 3D-generation integrations and accepts the extra installation, network, credential, and telemetry surface.
4. Do not run multiple add-on socket servers on the same host/port.

Read [references/mcp-options.md](references/mcp-options.md) before installing or replacing a Blender add-on.

## Mixamo browser integration

`blender_prepare_mixamo_search` returns a browser search URL and workflow, not
catalog results. Use host browser tools for live search, preview and download,
then `blender_import_mixamo_animation` for a new standalone animated `.blend`.
Adobe sign-in stays in the browser. See the animation workflow's
[Mixamo guide](../blender-animation-workflow/references/mixamo.md) for the
download settings, local import and retargeting limits.

## Pixabay sound-effects browser integration

`blender_prepare_pixabay_sound_search` returns a sound-effects search URL and
browser workflow, not live catalog results. Use host browser tools to inspect
results, preview candidates, and download the selected sound. Record its title,
creator, duration, and source page beside the local audio file. Check the
current [Pixabay Content License](https://pixabay.com/service/license-summary/)
for the intended use; do not redistribute the sound as a standalone asset.
Pixabay's [documented API](https://pixabay.com/api/docs/) covers images and
videos, so this tool does not use an audio API or scrape the catalog. It does
not import audio into a Blender scene.

## Optional scene analysis runtime

Use `blender_compare_reference` for a camera-matched reference/silhouette/overlay
board. It works directly through Blender without Rust and returns the image
inline. A reviewed white-on-black mask optionally enables projection metrics;
photos alone produce visual comparison, not guessed similarity scores. Author
the reference camera with bpy or the live MCP before comparing geometry.

`blender_describe_scene`, `blender_quality_report` and `blender_compare_scenes`
use the bundled Rust SceneIR analyzer. Run `bun run setup:runtime` in the installed plugin root with
a stable Rust toolchain, or set `BAS_RUNTIME_EXECUTABLE` to a compatible built
binary. Rebuild after updates. The existing tools remain independent of Rust.

Start with a compact scene description, then query an exact `objectId` and its
descendants. Bounds use evaluated world geometry. Semantic roles come only from
authored `bas_role` properties. Supply quality constraints from the brief;
ground checks require named objects and `groundZ`. AABB relations are candidates,
not exact mesh intersections. Keep the returned limitations and required visual
questions attached to the findings. No numerical aesthetic score is produced.

After a source-level repair, compare the preserved and regenerated assets with
`blender_compare_scenes`. Keep its factual changes separate from explicitly
declared invariant failures, and pair it with identical visual evidence. Use
`invariantObjects` when preservation gates should exclude the edited component.

## Preserve reproducibility

- Keep the durable model in a Python source file even when using live MCP execution.
- Save a new `.blend` before risky arbitrary-code operations.
- Use official MCP screenshots for interactive iteration.
- Use `$blender-agent-studio:blender-asset-validation` for final clean-process inspection and fixed evidence cameras.
- Record which MCP tools were used in benchmark runs.

## Benchmark MCP value

Compare:

1. plugin skills with MCP tools unavailable;
2. the same skills with the candidate MCP enabled.

Keep task, model, effort, time budget, and evaluator identical. Count execution failures, recovery turns, time, and final asset quality. Retain an MCP dependency only when it improves outcomes or materially reduces reliable completion cost.

• SKILL.md 6 KB
• agents/openai.yaml 1 KB
• references/astra-workflow.md 12 KB
• references/mcp-options.md 4 KB