dcc-mcp-blender

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:

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

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.

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) 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 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.

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; observe NASA media usage guidelines.

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.

┌─────────────────────────────────┐
│  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.2 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 by Darmstadt Graphics Group GmbH / Eric Chadwick (CC BY 4.0; Khronos logo trademark terms apply), Beach Parking HDRI by Poly Haven (CC0), and 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	`get_poly_count`, `cleanup_mesh`, `triangulate_mesh`, `separate_mesh`, `combine_meshes`, `merge_vertices`, `extract_faces`, `mirror_mesh`, `select_by_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`, `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`
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-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`, `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`
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`, `enable_addon`, `disable_addon`, `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`
blender-lighting	`create_light`, `set_light_properties`, `list_lights`, `set_world_background`
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`
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`, `list_simulation_modifiers`, `bake_simulation`, `clear_simulation_cache`, `get_simulation_status`

See 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

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:

帮我参考 dcc-mcp/dcc-mcp-blender/install.md 去安装

The agent follows install.md, which delegates the setup workflow to 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 4.2+ 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.

Download the latest platform ZIP from the 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
In Blender 4.2+: Edit → Preferences → Extensions → Install from Disk… → select the ZIP. (Do NOT use Edit → Preferences → Add-ons → Install — that legacy path is unsupported.)
Enable DCC MCP Blender
The MCP server starts on an OS-assigned instance port and registers with the local gateway.

Release ZIPs are Blender 4.2+ Extension packages. 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 4.2+ 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 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)

pip install dcc-mcp-blender

Then in Blender's Python console:

import dcc_mcp_blender
dcc_mcp_blender.start_server()

Headless Bootstrap

For CI or automation that needs Blender's main thread dispatcher:

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.

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:

{
  "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

import dcc_mcp_blender

# Start the server on an OS-assigned instance port
dcc_mcp_blender.start_server()

# Stop the server
dcc_mcp_blender.stop_server()

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`	Disable the `execute_python` tool to restrict arbitrary code execution.
`DCC_MCP_BLENDER_DISABLE_ARBITRARY_SCRIPT`	`false`	Disable 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.

Enabling Semantic Skill Recall

# 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.

Development

git clone https://github.com/dcc-mcp/dcc-mcp-blender
cd dcc-mcp-blender
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
docs		docs
packaging		packaging
skills/dcc-mcp-blender-setup		skills/dcc-mcp-blender-setup
src/dcc_mcp_blender		src/dcc_mcp_blender
tests		tests
tools		tools
.gitignore		.gitignore
.release-please-manifest.json		.release-please-manifest.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
glama.json		glama.json
install.md		install.md
integration_test.py		integration_test.py
justfile		justfile
llms.txt		llms.txt
pyproject.toml		pyproject.toml
release-please-config.json		release-please-config.json
renovate.json		renovate.json

Navigation Menu

Uh oh!

Repository files navigation

dcc-mcp-blender

Agent workflow

Install or update the CLI

Blender Extensions distribution

Overview

Showcase: stylized reference reconstruction

Showcase: rain-soaked PBR LookDev

Features

Available MCP Tools

Installation

Agent install (recommended)

Option 1 — Install as Blender Extension (ZIP, recommended)

Option 2 — Install via pip (for scripts / CI)

Headless Bootstrap

Quick Start

Claude Desktop

Python API

Configuration

Environment Variables

Enabling Semantic Skill Recall

Development

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

dcc-mcp-blender

Agent workflow

Install or update the CLI

Blender Extensions distribution

Overview

Showcase: stylized reference reconstruction

Showcase: rain-soaked PBR LookDev

Features

Available MCP Tools

Installation

Agent install (recommended)

Option 1 — Install as Blender Extension (ZIP, recommended)

Option 2 — Install via pip (for scripts / CI)

Headless Bootstrap

Quick Start

Claude Desktop

Python API

Configuration

Environment Variables

Enabling Semantic Skill Recall

Development

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages