dcc-mcp-blender 0.1.37

Blender addon for the DCC Model Context Protocol (MCP) ecosystem — embeds a Streamable HTTP MCP server directly inside Blender

dcc-mcp-blender

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.

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.)       │
└─────────────────────────────────┘

---

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

1. 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
2. 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.)
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 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. See packaging/release_smoke_checklist.md for the manual smoke test procedure.

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.