blender-mcp

<p align="center"> <img src="docs/logos/banner_2_wireframe.svg" alt="BlenderMCP — Talk to Blender." width="700"/> </p>

<p align="center"> <a href="https://github.com/kleer001/blender-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kleer001/blender-mcp?color=blue" alt="License: MIT"/></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJDNi40OCAyIDIgNi40OCAyIDEyczQuNDggMTAgMTAgMTAgMTAtNC40OCAxMC0xMFMxNy41MiAyIDEyIDJ6Ii8+PC9zdmc+" alt="MCP Compatible"/></a> <a href="https://www.blender.org/"><img src="https://img.shields.io/badge/Blender-4.2%20LTS-E87D0D?logoColor=white" alt="Blender 4.2 LTS"/></a> <a href="https://github.com/kleer001/blender-mcp/commits/main"><img src="https://img.shields.io/github/last-commit/kleer001/blender-mcp" alt="Last Commit"/></a> <a href="https://github.com/kleer001/blender-mcp/issues"><img src="https://img.shields.io/github/issues/kleer001/blender-mcp" alt="Issues"/></a> <a href="https://github.com/kleer001/blender-mcp/network/members"><img src="https://img.shields.io/github/forks/kleer001/blender-mcp?style=social" alt="Forks"/></a> <a href="https://github.com/kleer001/blender-mcp/watchers"><img src="https://img.shields.io/github/watchers/kleer001/blender-mcp?style=social" alt="Watchers"/></a> <a href="https://github.com/kleer001/blender-mcp/stargazers"><img src="https://img.shields.io/github/stars/kleer001/blender-mcp?style=social" alt="GitHub Stars"/></a> </p>

<p align="center"> <strong>175 MCP tools</strong> · <strong>25 domains</strong> · <strong>Integration-tested on Blender 4.2.5 LTS</strong> </p>

---

Control Blender from Claude (or any MCP-compatible AI) using the Model Context Protocol. BlenderMCP connects to your running Blender instance over a local TCP socket — your machine, your scenes, your assets.

Unlike existing Blender MCP projects that rely on execute_blender_code as a catch-all, this project provides dedicated, typed tools for every major Blender subsystem: objects, materials, shader nodes, geometry nodes, modifiers, animation, rigging, physics, compositing, and more.

Status

All 175 tools implemented and integration-tested against Blender 4.2.5 LTS. Full handler coverage across all 25 domains.

Requirements

• Python 3.10+
• uv (recommended) or pip
• Blender 4.0+ (for the addon)

Quick Start

# Clone and install
git clone https://github.com/kleer001/blender-mcp
cd blender-mcp
uv sync

# Run with mock Blender (no Blender needed)
uv run blender-mcp --mock

# Run against a real Blender instance
uv run blender-mcp

Blender Addon Setup

1. Copy the blender_addon/ directory to your Blender addons path, or symlink it
2. Enable Blender MCP in Blender → Edit → Preferences → Add-ons
3. In the 3D Viewport sidebar (N panel), find the MCP tab and click Start Server
4. Start the MCP server: uv run blender-mcp

Claude Code

The .mcp.json in the repo root auto-configures Claude Code. Just run claude from the project directory.

Claude Desktop

{
  "mcpServers": {
    "blender-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blender-mcp", "blender-mcp"]
    }
  }
}

Architecture

AI Client (Claude, Cursor, ChatGPT)
    │ MCP Protocol (stdio)
    ▼
MCP Server (src/blendermcp/)
    │ TCP Socket (localhost:9334)
    ▼
Blender Addon (blender_addon/)
    │ bpy API (main thread via timer queue)
    ▼
Blender

• MCP Server — FastMCP-based, runs as a separate process, communicates via stdio
• Blender Addon — TCP server inside Blender, dispatches commands to handlers on the main thread via bpy.app.timers
• Connection — JSON over TCP with newline framing, exponential backoff reconnection

Available Tools (175)

Domain	Count	Tools
Scene	6	ping · get_scene_info · load_file · save_file · set_frame · set_frame_range
Objects	12	get_object_info · list_objects · create_object · delete_object · set_transform · apply_transform · duplicate_object · rename_object · set_parent · clear_parent · set_origin · select_objects
Materials	8	list_materials · get_material_info · create_material · assign_material · remove_material · set_material_property · duplicate_material · delete_material
Shader Nodes	12	get_node_tree · create_shader_node · delete_shader_node · connect_shader_nodes · disconnect_shader_node · set_node_input · get_node_input · set_node_position · list_shader_node_types · create_node_group · add_node_group_instance · layout_node_tree
Geometry Nodes	10	get_geonodes_tree · create_geonodes_modifier · create_geonode · delete_geonode · connect_geonodes · disconnect_geonode · set_geonode_input · get_geonode_input · list_geonode_types · set_geonodes_input
Modifiers	8	list_modifiers · add_modifier · remove_modifier · set_modifier_property · apply_modifier · move_modifier · toggle_modifier_visibility · copy_modifiers
Animation	10	get_keyframes · set_keyframe · set_keyframes · delete_keyframe · clear_animation · get_action_info · list_actions · set_interpolation · set_playback_range · playback_control
Rigging	10	create_armature · get_armature_info · add_bone · set_bone_property · get_bone_info · parent_mesh_to_armature · assign_vertex_weights · add_bone_constraint · set_pose_bone_transform · list_bone_constraints
Constraints	6	list_constraints · add_constraint · remove_constraint · set_constraint_property · set_constraint_influence · reorder_constraint
Lighting	7	list_lights · create_light · set_light_property · create_hdri_world · set_world_property · get_world_info · create_light_rig
Camera	6	list_cameras · create_camera · set_camera_property · set_active_camera · camera_look_at · setup_camera_dof
Mesh Editing	8	get_mesh_info · get_vertices · set_vertices · get_vertex_groups · create_vertex_group · set_smooth_shading · separate_mesh · join_meshes
Curves	5	create_curve · get_curve_info · set_curve_points · set_curve_property · convert_to_mesh
Physics	10	add_physics · remove_physics · set_physics_property · get_physics_info · setup_rigid_body_world · setup_cloth_sim · setup_fluid_domain · setup_softbody · bake_physics · free_physics_bake
Particles	6	add_particle_system · remove_particle_system · set_particle_property · get_particle_info · setup_hair · bake_particles
Compositing	8	get_compositor_tree · enable_compositor · create_comp_node · delete_comp_node · connect_comp_nodes · set_comp_node_input · list_comp_node_types · setup_basic_composite
Sculpting	4	enter_sculpt_mode · set_sculpt_brush · remesh · apply_sculpt_mask
Grease Pencil	6	create_grease_pencil · get_gp_info · add_gp_layer · set_gp_layer_property · create_gp_stroke · add_gp_modifier
Textures & UV	6	list_images · load_image · get_uv_maps · create_uv_map · smart_uv_project · pack_images
Viewport	6	get_viewport_info · capture_viewport · set_viewport_shading · set_viewport_camera · frame_selected · frame_all
Rendering	6	get_render_settings · set_render_settings · render_image · render_animation · render_viewport · list_render_engines
Collections	5	list_collections · create_collection · move_to_collection · set_collection_visibility · delete_collection
Import/Export	4	import_file · export_file · list_supported_formats · export_selection
Code Execution	2	execute_python · evaluate_expression
Batch Operations	4	find_objects · batch_set_property · batch_delete · find_error_objects

Development

# Install with dev dependencies
uv sync

# Run tests (unit, no Blender needed)
uv run pytest tests/ --ignore=tests/integration -v

# Run integration tests (requires Blender at /opt/blender-4.2/blender)
uv run pytest tests/integration/ -v -m integration

# Run with mock (no Blender needed)
uv run blender-mcp --mock --debug

# Lint
uv run ruff check src/ tests/

License

MIT