dcc-mcp-blender
by dcc-mcp
README.md
# dcc-mcp-blender
[](https://mcptoplist.com/server/glama%2Fdcc-mcp%2Fdcc-mcp-blender)
<p align="center">
<img src="docs/assets/dcc-mcp-blender.svg" alt="DCC-MCP · BLENDER" width="600">
</p>
<!-- dcc-mcp-agent-quickstart:start -->
## Use Blender with AI agents
Install the official DCC-MCP Agent Skill. Codex users can use the native plugin
marketplace:
```powershell
codex plugin marketplace add dcc-mcp/dcc-mcp-agent-plugins
codex plugin add dcc-mcp@dcc-mcp
```
For Claude Code, CodeBuddy, Cursor, Gemini CLI, and other supported agents, use
the [official installation guide](https://github.com/dcc-mcp/dcc-mcp-agent-plugins#install). Start Blender,
enable this adapter, and verify that the running instance is registered:
```powershell
dcc-mcp-cli list
```
Then ask your agent:
```text
Use dcc-mcp to inspect the current Blender scene.
```
The list must include `dcc_type=blender`. If it does not, follow the
[connection troubleshooting guide](https://github.com/dcc-mcp/dcc-mcp-agent-plugins#adapter-connection-troubleshooting).
<!-- dcc-mcp-agent-quickstart:end -->
<!-- dcc-mcp-coverage-pointer:start -->
<!-- Generated from dcc-mcp-catalog.yml by scripts/generate_adapter_pointer.py in dcc-mcp/dcc-mcp-core. Do not edit by hand. -->
## Part of the DCC-MCP host matrix
**dcc-mcp-blender** — Core Blender adapter for DCC-MCP — Blender add-on with in-process
MCP server.
It is one of **47 host adapters** in the DCC-MCP catalog. Every adapter speaks the same
MCP protocol and builds on the same core runtime contract; each one exposes the tools
its own host needs on top of that.
- [All host adapters and install metadata](https://dcc-mcp.github.io/ecosystem)
- [Host matrix on the core README](https://github.com/dcc-mcp/dcc-mcp-core#readme)
- [Showcase](https://dcc-mcp.github.io/showcase)
This block is generated from the catalog entry in
[`dcc-mcp-catalog.yml`](https://github.com/dcc-mcp/dcc-mcp-core/blob/main/dcc-mcp-catalog.yml).
Re-run the generator after changing the catalog.
<!-- dcc-mcp-coverage-pointer:end -->
## Showcase: weathered crate and material reconstruction
A 2.2 m reference-guided crate with layered broken wood, SD height displacement,
rusted steel reflections and verified floor contact. Modeling, UVs and lookdev
are editable in Blender; paint, grain, scratches and rust are authored in
Substance 3D Designer.
| UV coordinates | Checker on the model |
| --- | --- |
|  |  |
[Scene, detail renders and UV explanation](docs/showcase/crate-lookdev/README.md) ·
[Designer materials and full node workflow](https://github.com/dcc-mcp/dcc-mcp-substance3d-designer/tree/main/docs/showcase/crate-lookdev) ·
[Website gallery](https://dcc-mcp.github.io/showcase)
## Agent workflow
AI agents should use the shared gateway through `dcc-mcp-cli`; IDE users may
continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.
### Install or update the CLI
`dcc-mcp-cli` is the preferred control path for every shell-capable agent. If
it is missing, ask the user before installing the latest official release:
```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"
```
Keep an official build current through the release manifest:
```bash
dcc-mcp-cli update check
dcc-mcp-cli update apply
```
`update apply` downloads and stages the latest CLI for the next launch. It
does not update a running `dcc-mcp-server`; update that server in its own
environment.
```bash
dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type blender
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'
```
`dcc-types` reports release-catalog support; `list` reports live sessions. If a
tool belongs to an inactive progressive skill, call `dcc-mcp-cli load-skill <skill-name> --dcc-type blender` before retrying. For post-task improvement,
attach a stable session id with `--meta-json`, query `dcc-mcp-cli stats --range 24h --session-id <task-id>`, then pass the bounded evidence to the
`review_skill_improvement` prompt from `dcc-mcp-skills-creator`.
> Blender addon for the [DCC Model Context Protocol (MCP)](https://github.com/dcc-mcp/dcc-mcp-core) ecosystem — embeds a Streamable HTTP MCP server directly inside Blender, letting any MCP-compatible AI client drive your 3D workflow.
## Blender Extensions distribution
The source repository and PyPI package are MIT licensed. The ZIP submitted to
[Blender Extensions](https://extensions.blender.org/) is GPL-3.0-or-later, as
required for add-ons listed there; it also retains the bundled MIT notice.
Download the platform-specific ZIP from the GitHub Release and install it with
**Preferences → Get Extensions → Install from Disk**.
[](https://badge.fury.io/py/dcc-mcp-blender)
[](https://pypi.org/project/dcc-mcp-blender/)
[](https://pypi.org/project/dcc-mcp-blender/#files)
[](https://github.com/dcc-mcp/dcc-mcp-blender/actions/workflows/ci.yml)
[](https://github.com/dcc-mcp/dcc-mcp-blender/actions/workflows/e2e.yml)
[](https://github.com/dcc-mcp/dcc-mcp-blender/actions/workflows/release.yml)
[](https://pypi.org/project/dcc-mcp-blender/)
[](https://github.com/dcc-mcp/dcc-mcp-blender/releases)
[](https://github.com/dcc-mcp/dcc-mcp-blender/releases)
[](https://github.com/dcc-mcp/dcc-mcp-blender/blob/main/pyproject.toml)
[](https://github.com/dcc-mcp/dcc-mcp-core)
[](https://www.blender.org/download/)
[](https://modelcontextprotocol.io/)
[](https://opensource.org/licenses/MIT)
<p align="center">
<img src="docs/images/dcc-mcp-blender-showcase.webp"
alt="Blender MCP production proof showing a Cycles-rendered galaxy built with Mantaflow nebula volumes, Geometry Nodes particles, PBR materials, render layers, and Compositor finishing"
width="960"
loading="lazy" />
</p>
*Built through live `dcc-mcp-blender` calls with a baked Mantaflow/OpenVDB
nebula, Geometry Nodes particles, native PBR materials, four Cycles view layers,
and Blender Compositor finishing. The subtle Crab Nebula-derived point pass uses
[NASA 3D Resources](https://github.com/nasa/NASA-3D-Resources/tree/master/3D%20Printing/Crab%20Nebula);
observe [NASA media usage guidelines](https://www.nasa.gov/nasa-brand-center/images-and-media/).*
---
## Overview
`dcc-mcp-blender` turns Blender into a first-class MCP server. Once the addon is enabled, any MCP client (Claude Desktop, custom agents, etc.) can call Blender tools over HTTP without any external gateway.
See [MCP protocol compatibility](docs/protocol-compatibility.md) for the
adapter-facing negotiation matrix and contract test command.
See [capability enhancement](docs/capability-enhancement.md) for live RNA
parameter discovery, bounded modifier readback, and the validation rubric.
```
┌─────────────────────────────────┐
│ Blender (Python 3.10+) │
├─────────────────────────────────┤
│ dcc_mcp_blender │
│ ├─ BlenderMcpServer │
│ ├─ SkillCatalog (200+ tools) │
│ ├─ ActionRegistry │
│ └─ HTTP Handlers │
├─────────────────────────────────┤
│ dcc-mcp-core │
│ ├─ McpHttpServer │
│ ├─ JSON-RPC 2.0 │
│ └─ SSE Streaming │
└─────────────────────────────────┘
↓ http://127.0.0.1:9765/mcp (stable gateway)
┌─────────────────────────────────┐
│ MCP Host (Claude / etc.) │
└─────────────────────────────────┘
```
---
## Showcase: stylized reference reconstruction
This reference-guided Blender scene was refined through a long render-and-compare
loop rather than replaced with a painted image. The final frame preserves editable
seat, suspension, chain, and tiled-floor geometry while matching the reference's
flattened red materials, projected support shadow, restrained floor gradient,
subtle bloom, and cinematic letterboxing. The split view pairs the finished render
with a same-camera wireframe generated from the evaluated scene geometry.
Reusable prompt: Use the dcc-mcp Skill to connect to Blender and reconstruct the
supplied stylized swing reference as a fully editable 3D scene. Match the two
parallel seats, suspension arcs and flattened chain links, overhead support and
its continuous projected shadow, tiled floor, orthographic composition, red
material treatment, directional lower-right seat gradient, distant overexposure,
subtle bloom, and cinematic letterboxing. Work in an iterative render-reference
comparison loop: after every preview, measure silhouette, screen-space alignment,
shadow angle and continuity, tile visibility, highlight falloff, and material
flatness; correct geometry, lighting, materials, and compositor settings without
replacing the scene with a painted image. Preserve a real mesh scene, save the
`.blend`, render the final 16:9 frame, and report validation evidence and output
paths.
---
## Showcase: rain-soaked PBR LookDev
This live Blender 4.5 test moves from the imported mesh wireframe to a Cycles
PBR beauty render, then rotates an HDRI and three-point light rig through 360°
while a heavy particle rain simulation interacts with the sports car and wet
ground. It exercises asset import, clearcoat and transmission materials,
particle instancing and collision, depth of field, atmosphere, color
management, lighting, animation, and final rendering through MCP.
Showcase assets: [Car Concept](https://github.com/KhronosGroup/glTF-Sample-Assets/tree/main/Models/CarConcept)
by Darmstadt Graphics Group GmbH / Eric Chadwick (CC BY 4.0; Khronos logo
trademark terms apply), [Beach Parking](https://polyhaven.com/a/beach_parking)
HDRI by Poly Haven (CC0), and
[Easy Clouds](https://extensions.blender.org/add-ons/easy-clouds/) (GPL-3.0-or-later).
---
## Features
- **Embedded MCP server** — no external gateway needed; the server runs inside Blender's Python interpreter
- **200+ pre-built tools** — scene management, object manipulation, mesh/UV editing, rigging, pose libraries, interchange, materials, node graphs, rendering, physics, scripting, cross-DCC import and more
- **Extensible skill system** — drop new skill folders alongside built-ins or point to them via env vars
- **Main-thread host adapter** — GUI mode uses core `HostUiDispatcherBase` semantics through `BlenderUiDispatcher`; headless mode uses `BlenderHost` with a core `BlockingDispatcher`
- **Streamable HTTP transport** — compatible with any MCP 2025-03-26 client
- **Claude Desktop ready** — ship a one-line `mcpServers` config and you're done
---
## Available MCP Tools
| Category | Tools |
|---|---|
| **blender-scene** | `new_scene`, `open_scene`, `save_scene`, `list_objects`, `get_scene_info`, `get_session_info` |
| **blender-objects** | `create_object`, `delete_object`, `duplicate_object`, `move_object`, `rotate_object`, `scale_object`, `get_object_info`, `get_selection`, `set_selection`, `select_by_type`, `find_by_pattern`, `rename_object`, `parent_object`, `group_objects`, `set_visibility`, `get_bounding_box`, `center_origin`, `freeze_transforms` |
| **blender-mesh** | `add_modifier`, `apply_modifier`, `list_modifiers`, `get_mesh_info` |
| **blender-mesh-ops** | Default `mesh-edit` inspection/cleanup tools plus the opt-in `modeling` group: `create_primitive`, `loft_sections`, `lathe_profile`, `extrude_faces`, `bevel_edges`, `inset`, `boolean_op`, `add_edge_loop`, `array_instances`, `mirror`, `set_pivot`, `group_parent`, `freeze_transforms`, `delete_history`, `auto_uv`, `uv_project`, `assign_material` |
| **blender-uv-ops** | `list_uv_maps`, `create_uv_map`, `delete_uv_map`, `copy_uv_map`, `get_uv_info`, `get_uv_islands`, `project_uvs`, `unwrap_uvs`, `pack_uvs`, `normalize_uvs` |
| **blender-rigging** | `create_armature`, `create_bone`, `mirror_bones`, `inspect_armature`, `set_pose_bone_transforms`, `add_constraint`, `set_constraint_properties`, `bind_mesh_to_armature`, `add_shape_key`, `set_driver`, `retarget_animation` |
| **blender-pose-library** | `list_poses`, `save_pose`, `load_pose` |
| **blender-import-to-scene** | `import_to_scene` |
| **blender-interchange** | `import_file`, `import_fbx`, `import_obj`, `import_usd`, `export_gltf`, `export_usd`, `export_alembic`, `batch_export` |
| **blender-export-preset** | `list_export_presets`, `save_export_preset`, `load_export_preset`, `delete_export_preset` |
| **blender-shot-export** | `get_shot_info`, `export_camera` |
| **blender-validation** | `run_scene_checks`, `validate_mesh`, `validate_materials`, `validate_animation`, `validate_export_readiness`, `get_validation_report` |
| **blender-pipeline** | `get_asset_metadata`, `tag_asset_metadata`, `clear_asset_metadata`, `set_project_context`, `create_publish_manifest`, `prepare_publish_package` |
| **blender-materials** | `create_material`, `assign_material`, `set_material_color`, `list_materials`, `delete_material`, `export_materialx`, `import_materialx` |
| **blender-shader-nodes** | `list_material_nodes`, `set_principled_input`, `list_node_trees`, `list_nodes`, `create_node`, `delete_node`, `list_node_sockets`, `connect_nodes`, `disconnect_nodes`, `list_node_links`, `set_node_input`, `get_node_value`, `create_material_with_nodes`, `assign_texture_node`, `set_principled_inputs` |
| **blender-compositor** | `setup_compositor_tree`, `set_compositor_enabled`, `clear_compositor_tree`, `create_compositor_node`, `delete_compositor_node`, `connect_compositor_nodes`, `disconnect_compositor_nodes`, `set_compositor_node_value`, `get_compositor_node_value`, `list_compositor_node_links`, `list_compositor_node_types` |
| **blender-material-library** | `save_material_preset`, `list_material_presets`, `load_material_preset`, `delete_material_preset`, `get_shader_assignment`, `get_material_connections`, `set_material_attribute`, `assign_texture`, `list_images`, `reload_image`, `load_image`, `save_image`, `pack_image`, `unpack_image`, `image_file_status`, `list_image_tiles`, `list_color_spaces`, `set_color_management` |
| **blender-texture-bake** | `list_bake_targets`, `bake_textures`, `bake_ambient_occlusion`, `bake_lighting`, `transfer_maps` |
| **blender-render** | `render_scene`, `set_render_settings`, `get_render_info`, `capture_viewport`, `get_view_layer_passes`, `set_view_layer_passes`, `set_render_denoise`, `get_render_output`, `set_render_output`, `set_render_region`, `clear_render_region`, `get_render_status` |
| **blender-render-farm** | `validate_scene_for_farm`, `write_render_job`, `submit_render_job`, `get_render_job_status`, `list_render_jobs`, `cancel_render_job`, `cooperative_cancel`, `render_farm_status` |
| **blender-scripting** | `execute_python`, `execute_script_file`, `get_blender_info` |
| **blender-dev** | `attach_project`, `reload_modules`, `run_check`, `run_entrypoint`, `run_script`, `list_addons`, `get_addon_status`, `install_addon`, `enable_addon`, `disable_addon`, `remove_addon`, `refresh_addons`, `capture_ui_snapshot`, `find_ui_elements`, `start_debug_server`, `get_python_environment` |
| **blender-animation** | `set_keyframe`, `set_frame_range`, `get_frame_range`, `set_current_frame`, `get_keyframes`, `delete_keyframes`, `bake_animation`, `list_animation_actions`, `list_nla_tracks`, `add_nla_track`, `remove_nla_track`, `add_nla_strip`, `set_nla_strip`, `remove_nla_strip`, `list_action_fcurves`, `set_action_fcurve_extrapolation` |
| **blender-lighting** | `create_light`, `set_light_properties`, `list_lights`, `set_world_background`, `set_light_linking`, `set_light_ies` |
| **blender-light-rig** | `create_three_point_light_rig`, `create_area_softbox`, `create_hdri_world`, `animate_hdri_rotation`, `list_light_rigs`, `set_light_rig_intensity`, `aim_light_at_object`, `group_lights`, `set_render_view_transform`, `get_lighting_summary` |
| **blender-camera** | `create_camera`, `set_active_camera`, `set_camera_properties`, `list_cameras` |
| **blender-collection** | `create_collection`, `link_to_collection`, `list_collections` |
| **blender-geometry** | `create_sphere`, `save_blend`, `file_exists`, `export_fbx`, `export_obj` |
| **blender-geometry-nodes** | `add_geometry_nodes_modifier`, `list_geometry_nodes_modifiers`, `create_geometry_node_group`, `assign_geometry_node_group`, `set_geometry_node_modifier_input`, `evaluate_geometry_nodes_info`, `inspect_geometry_node_interface`, `create_geometry_node_socket`, `update_geometry_node_socket`, `remove_geometry_node_socket` |
| **blender-physics** | `add_rigid_body`, `set_rigid_body_properties`, `remove_rigid_body`, `list_rigid_bodies`, `set_rigid_body_world_settings`, `bake_rigid_body_simulation`, `clear_rigid_body_bake`, `add_cloth_modifier`, `set_cloth_settings`, `add_collision_modifier`, `set_collision_settings`, `add_soft_body_modifier`, `set_soft_body_settings`, `add_rigid_body_constraint`, `remove_rigid_body_constraint`, `list_rigid_body_constraints`, `add_force_field`, `remove_force_field`, `list_force_fields`, `add_particle_system`, `set_particle_system_settings`, `list_particle_systems`, `list_simulation_modifiers`, `bake_simulation`, `clear_simulation_cache`, `get_simulation_status`, `add_fluid_modifier`, `set_fluid_settings`, `add_dynamic_paint_modifier`, `set_dynamic_paint_settings`, `add_dynamic_paint_surface`, `list_dynamic_paint_surfaces`, `set_particle_hair`, `set_particle_children`, `set_particle_instance`, `bake_particle_system` |
### glTF / GLB export vertex counts
`export_gltf` writes a file whose vertex count is **systematically higher than the
shared-vertex count Blender reports for the same mesh**. glTF stores one vertex per
unique normal + UV combination, so a differing count is expected behavior, not an
export defect.
- **Rule of thumb:** hard-edged / flat-shaded meshes split the most (typically
2x-4x; more for meshes with many UV islands or per-vertex color/skin splits;
a default cube is 8 vertices in Blender and 24 in GLB), while smooth-shaded
meshes approach 1x. UV seams, tangents, vertex colors, skin weights and
multi-material boundaries also split vertices, so a smooth-shaded mesh can
still land above 1x.
- **Measured example:** a 3-part white-clay model exported from Blender reported 554
vertices in-host and 2200 in GLB (~4x): cube 8 -> 24, sphere 482 -> 1984,
cylinder 64 -> 192.
- **How to validate:** `export_gltf` returns no vertex / face / material metrics.
Re-import the asset with `import_file` and inspect it with `get_mesh_info`, run
`blender-validation` checks such as `validate_mesh` and `validate_export_readiness`,
or use an external glTF validator.
See [`src/dcc_mcp_blender/skills/SKILLS_INDEX.md`](src/dcc_mcp_blender/skills/SKILLS_INDEX.md) for staged loading guidance, task-to-skill chains, and side-effect profiles for all bundled skills.
---
## Installation
### Blender compatibility
**Blender 4.5 is the minimum supported host version.** The CI targets are
**Blender 4.5.13 LTS** (bundled Python 3.11) and **Blender 5.2.1** (Python 3.13), using
SHA256-verified official archives on Windows x64, Linux x64, and macOS arm64.
Hosts older than 4.5 are rejected at install time and are not tested. See the
[official release list](https://www.blender.org/releases/) and
[exact-version E2E matrix](.github/workflows/e2e.yml).
Blender 5.x Geometry Nodes inputs use RNA properties; animation readback,
deletion, and interpolation use the object's assigned Action Slot. Windows
runtime DLLs must match Blender's Python minor version.
CI runs real background Blender tests and separate-process MCP smoke tests on
every matrix entry. Background tests do not establish GUI, GPU,
shared-gateway CLI, or whole-software workflow acceptance. Consult the
[capability coverage and delivery phases](docs/capability-coverage.md) for
known gaps; raw Python execution is not counted as typed workflow coverage.
### Agent install (recommended)
Want an AI agent to install the Blender-side dependencies, write the MCP host
config, and walk you through enabling the add-on? Just ask your agent:
```text
帮我参考 dcc-mcp/dcc-mcp-blender/install.md 去安装
```
The agent follows [`install.md`](install.md), which delegates the setup workflow
to [`skills/dcc-mcp-blender-setup`](skills/dcc-mcp-blender-setup). The remaining
options below are for manual installation.
### Option 1 — Install as Blender Extension (ZIP, recommended)
> **Important:** The release ZIP uses the **Blender Extension** format with
> `blender_manifest.toml` at the archive root and a flat package layout.
> **Legacy add-on install** (`Edit → Preferences → Add-ons → Install`) will
> fail with *"ZIP packaged incorrectly; `__init__.py` should be in a
> directory, not at top-level"*. This is expected — use the Extensions path
> below. The Extension format is the **only supported GUI installation path**.
1. Download the latest platform ZIP from the [Releases](https://github.com/dcc-mcp/dcc-mcp-blender/releases) page:
`dcc_mcp_blender_addon_win64_vX.Y.Z.zip`, `dcc_mcp_blender_addon_linux_vX.Y.Z.zip`, or
`dcc_mcp_blender_addon_macos_vX.Y.Z.zip`
2. In Blender 4.5+: **Edit → Preferences → Extensions → Install from Disk…** → select the ZIP.
(Do **NOT** use **Edit → Preferences → Add-ons → Install** — that legacy path is unsupported.)
3. Enable **DCC MCP Blender**
4. The MCP server starts on an OS-assigned instance port and registers with the local gateway.
Release ZIPs are Blender Extension packages for Blender 4.5+. They include `blender_manifest.toml` and the matching `dcc-mcp-core` wheel under `wheels/`, so Blender installs the Python dependency into the extension's isolated environment.
The extension ZIP is assembled by `packaging/assemble_zip.py`. It resolves the latest compatible `dcc-mcp-core` wheel, places it under `wheels/`, and injects that wheel into `blender_manifest.toml`; Blender then installs it through the extension wheel mechanism instead of relying on global `pip` packages or `sys.path` edits. Build locally with `just blender-addon-zip` for the host platform, or `just blender-addon-zip win64 dist_addon` (replace `win64` with `linux` or `macos`) for an explicit target. See [`packaging/release_smoke_checklist.md`](packaging/release_smoke_checklist.md) for the manual smoke test procedure.
Native UI Control requires standalone `dcc-cua` 0.4.0 or newer on `PATH` (or
`DCC_MCP_CUA_BINARY`). Core owns the `ui_control__*` contract; the Blender ZIP
does not bundle a second capture or input helper. At startup, the extension
binds UI Control to the current Blender process ID and refuses a conflicting
process binding, so a request cannot widen the adapter to another window.
### Option 2 — Install via pip (for scripts / CI)
```bash
pip install dcc-mcp-blender
```
Then in Blender's Python console:
```python
import dcc_mcp_blender
dcc_mcp_blender.start_server()
```
### Headless Bootstrap
For CI or automation that needs Blender's main thread dispatcher:
```bash
blender --background --python src/dcc_mcp_blender/blender_bootstrap.py
```
The bootstrap prints `MCP_URL=...`, discovers bundled skills, and drives `BlenderHost` in headless mode until the process is stopped.
On Blender 5.x the bootstrap also restores `PYTHONPATH` entries that the isolated interpreter dropped, so the same command works without `--python-use-system-env`. See [Blender 5.x and isolated Python](#blender-5x-and-isolated-python).
In interactive add-on mode, `BlenderUiDispatcher` subclasses the shared core UI dispatcher and `BlenderTimerPump`
contains the Blender-specific `bpy.app.timers` wiring. In background mode, `BlenderHost` keeps using core
`BlockingDispatcher` with an explicit headless loop so automation does not depend on Blender UI timers.
---
## Quick Start
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"blender": {
"url": "http://127.0.0.1:9765/mcp"
}
}
}
```
Make sure the Blender addon is enabled and the server is running, then restart Claude Desktop.
### Python API
```python
import dcc_mcp_blender
# Start the server on an OS-assigned instance port
server = dcc_mcp_blender.start_server()
print(server.mcp_url)
# Stop the server
dcc_mcp_blender.stop_server()
```
To keep a private local gateway while disabling its additional remote listener,
start a fresh server with explicit options:
```python
server = dcc_mcp_blender.start_server(
port=0,
gateway_port=19765,
gateway_remote_port=0,
enable_gateway_failover=False,
registry_dir="./private-dcc-mcp-registry",
)
```
`gateway_remote_host` and `gateway_remote_port` are keyword-only options on
`start_server()` and `BlenderMcpServer`, and fields on `BlenderServerOptions`.
`None` preserves Core's defaults and environment configuration, including the
existing LAN listener behavior. `gateway_remote_port=0` disables only the
embedded gateway's additional remote listener; the nonzero `gateway_port` still
enables local gateway registration. `enable_gateway_failover=False` controls
automatic failover separately and does not disable the remote listener.
Explicit remote arguments and the Core environment overrides
`DCC_MCP_GATEWAY_REMOTE_HOST` / `DCC_MCP_GATEWAY_REMOTE_PORT` require a Core build
exposing the public remote gateway options; unsupported builds raise
`RuntimeError`. Stop an existing singleton with `stop_server()` before changing
remote settings. Explicit remote arguments are rejected on a running singleton;
changing environment variables does not reconfigure it.
---
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `DCC_MCP_BLENDER_SEMANTIC_INDEX` | `0` (off) | Set to `1` to enable the opt-in lexical+vector hybrid skill recall. When enabled, `search_skills` fuses BM25 with vector similarity via Reciprocal Rank Fusion (RRF), improving recall for natural-language queries like "import USD files" or "rendering a preview". |
| `DCC_MCP_BLENDER_SEMANTIC_EMBEDDER` | `hashed` | Embedder backend for semantic recall. `hashed` (default) uses a zero-dependency hash-based embedding. Set to `onnx` for dense embeddings via `OnnxEmbedder` (requires `pip install 'dcc-mcp-core[semantic]'`). |
| `DCC_MCP_BLENDER_READINESS_TIMEOUT_SECS` | *(none)* | Optional timeout in seconds for the readiness probe's dcc verification step. |
| `DCC_MCP_BLENDER_METRICS` | `false` | Enable Prometheus `/metrics` HTTP endpoint. |
| `DCC_MCP_BLENDER_JOB_STORAGE` | *(auto)* | Directory for render-job SQLite persistence; auto-resolves to platform tempdir when unset. |
| `DCC_MCP_BLENDER_STRICT_SKILL_SCAN` | `false` | Raise on invalid skill YAML instead of logging a debug warning and skipping. |
| `DCC_MCP_BLENDER_ENABLE_WORKFLOWS` | `true` | Enable workflow orchestration surface (`workflows.run`, `workflows.resume`, etc.). |
| `DCC_MCP_BLENDER_ENABLE_GATEWAY_FAILOVER` | `true` | Enable gateway failover for high-availability configurations. |
| `DCC_MCP_BLENDER_DISABLE_EXECUTE_PYTHON` | `false` | Refuse the `execute_python` and `execute_script_file` escape hatches to restrict arbitrary code execution. |
| `DCC_MCP_BLENDER_DISABLE_ARBITRARY_SCRIPT` | `false` | Refuse all arbitrary script execution; implies `DCC_MCP_BLENDER_DISABLE_EXECUTE_PYTHON`. |
| `DCC_MCP_BLENDER_PROJECT_TOOLS` | *(none)* | Set to `0` to opt out of the four `project_*` MCP tools. |
| `DCC_MCP_BLENDER_RESOURCES` | *(none)* | Set to `0` to opt out of MCP resource publishing (e.g. `scene://current`). |
| `DCC_MCP_BLENDER_SKILL_PATHS` | *(none)* | Additional `os.pathsep`-delimited skill search paths extending the bundled set. |
| `DCC_MCP_SKILL_PATHS` | *(none)* | Shared across all DCC-MCP packages; skill-path search falls back here when the Blender-specific var is unset. |
| `DCC_MCP_BLENDER_PYTHONPATH_REPAIR` | `1` (on) | Restore launcher-injected `PYTHONPATH` entries inside hosts that ignore them (Blender 5.x). Set to `0` to opt out. |
| `DCC_MCP_BLENDER_EXTRA_SITE_DIRS` | *(none)* | Extra `os.pathsep`-delimited directories to make visible on any host; useful when `PYTHONPATH` is stripped by the launcher. |
#### Blender 5.x and isolated Python
Blender 5.x starts its embedded interpreter with an isolated CPython config
(`sys.flags.isolated` / `sys.flags.ignore_environment` set), so `PYTHONPATH` is
**not** read: dependencies injected by a package manager or CI resolve never
reach `sys.path`, and the host ends up with zero adapter capability while the
resolve reports success.
The adapter repairs this from the inside — the process environment is still
readable even when `PYTHONPATH` is ignored, so the entries are restored before
any adapter import. It happens automatically when you use:
- the add-on / extension (repaired before the first adapter import), or
- `blender --background --python src/dcc_mcp_blender/blender_bootstrap.py`, or
- any script that imports `dcc_mcp_blender` once the package itself is visible.
For scripts that must import the adapter before it is on `sys.path`, either
launch Blender with `--python-use-system-env` (Blender's own switch to honour
`PYTHONPATH` again) or run the doctor first — it is a no-op on hosts that
already honour `PYTHONPATH`:
```bash
blender --background --python tools/blender_path_doctor.py -- --deep
```
The doctor prints the interpreter flags, how many `PYTHONPATH` entries the host
can see, which packages resolve and from where, and the reachable tool surface.
It exits non-zero when the adapter is not importable, so a resolve that yields
an unusable host fails loudly instead of silently.
#### Enabling Semantic Skill Recall
```bash
# Enable hybrid BM25 + vector recall
export DCC_MCP_BLENDER_SEMANTIC_INDEX=1
# Optional: use ONNX for dense embeddings (better semantic matching)
pip install 'dcc-mcp-core[semantic]'
export DCC_MCP_BLENDER_SEMANTIC_EMBEDDER=onnx
```
When enabled, skill search results include a `[semantic]` extra field and RRF-fused scores.
The feature is **opt-in** — BM25-only recall remains the default and is not affected when the
env var is unset.
---
## When to use the "official" Blender MCP vs dcc-mcp-blender
**There is no Blender-official MCP server.** If you arrived here searching for the
"official Blender MCP", you are most likely looking for
[`mcp-for-blender`](https://github.com/ahujasid/mcp-for-blender) (formerly
`blender-mcp`), a widely used community project whose README states:
> **Disclaimer:** This is a third-party integration and not made by Blender
The `blender` GitHub organization publishes no MCP server, and neither the
Blender source tree nor the bundled add-on tree contains MCP code. Verified on
2026-09-23.
Both projects let an agent drive Blender. They optimize for different work:
- **`mcp-for-blender`** — the fast, exploratory path. A Blender add-on opens a
socket server and a separate process relays MCP over it. It supports Blender
3.0+, runs arbitrary Python by default, and bundles generative-3D and asset
integrations (Poly Haven, Sketchfab, Poly Pizza, Hyper3D Rodin, Hunyuan3D).
Set `BLENDER_MCP_SAFE_MODE=1` to pre-check generated scripts; note that the
add-on socket has no authentication or encryption.
- **`dcc-mcp-blender`** — the production path. The MCP server runs embedded in
Blender with no external process, exposing 200+ typed tools across 25+ skill
packages over Streamable HTTP. Typed tools are schema-validated and testable,
the `execute_python` and `execute_script_file` escape hatches can be switched
off with `DCC_MCP_BLENDER_DISABLE_ARBITRARY_SCRIPT`, and Blender shares one
gateway and CLI with Maya, Houdini, USD and 3ds Max.
Pick `mcp-for-blender` for prompt-assisted exploration on a single machine.
Pick `dcc-mcp-blender` for pipeline work, cross-DCC automation, headless/CI
runs, and places where you want to constrain what the agent can execute.
See [Blender MCP vs dcc-mcp-blender](docs/blender-mcp-comparison.md) for the
full comparison, including the architecture, version, and security rows.
### Extending with marketplace skills
Third-party models and asset libraries are **not** bundled into this adapter.
Install them as marketplace skills instead:
```bash
dcc-mcp-cli marketplace search
dcc-mcp-cli marketplace install dcc-asset-polyhaven
dcc-mcp-cli marketplace install dcc-ai-hunyuan3d
```
Generative-3D and asset integrations available this way include
`dcc-ai-hunyuan3d`, `dcc-ai-tripo3d`, `dcc-asset-polyhaven`,
`dcc-asset-sketchfab`, `dcc-asset-poly-pizza` and `dcc-asset-ambientcg`. The
catalog is the source of truth — run `dcc-mcp-cli marketplace search` for the
current list.
---
## Development
```bash
git clone https://github.com/dcc-mcp/dcc-mcp-blender
cd dcc-mcp-blender
pip install -e ".[dev]"
pytest
```
---
## License
MIT — see [LICENSE](LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessWithin a week