Skip to content

About

Local MCP server + Blender 5.2 extension: 159 tools to drive Blender from Claude Code

Resources

Stars

6 stars

Watchers

1 watching

Forks

Repository files navigation

English | 中文

blender_mcp — a local blender-mcp

Drive your local Blender 5.2 LTS from Claude Code (or any MCP client) in plain language: 17 categories, 159 typed tools covering modeling, materials, node trees, lighting, animation, cameras, rendering, import/export, UV and baking, batch operations, assets, rigging, and one-shot workflows.

  • Platforms: macOS / Windows / Linux (all three tested)
  • Blender: 5.2 LTS (not compatible with 4.x)
  • Requirements: Python 3.11+, uv
  • License: MIT

Highlights

  • 159 typed tools: every tool has an explicit signature and description, so the model never has to guess the bpy API. execute_code is the escape hatch for arbitrary Python.
  • Fully local, zero-network add-on: the Blender add-on only listens on 127.0.0.1:9877 and never touches the network. Poly Haven / Sketchfab downloads happen in the MCP server process and are written to disk before the add-on imports them by path.
  • Readable errors: when an object / material / node / socket is not found, the error lists candidate names and is passed through to the model verbatim, so it can self-correct.
  • Undoable: every write is a Ctrl+Z step in Blender; undo / redo tools are available in GUI mode.
  • One-shot workflows: three-point lighting, studio scene, turntable animation, product render, material from a texture folder, surface scatter, game-asset export.
  • Offline API docs: get_api_docs("bpy.types.Object.location") looks up bpy documentation without going online.
  • Visual feedback: render_image / viewport_screenshot can return the image straight to the model.

Architecture

Claude Code ──stdio──▶ MCP server (src/blender_mcp_pro, Python 3.11+ managed by uv)
                            │  each tool: typed signature → {tool, params} JSON forward
                            ▼
                    127.0.0.1:9877 (4-byte length prefix + JSON frames, persistent connection)
                            │
                Blender 5.2 extension (addon/blender_mcp_pro, Blender's bundled Python 3.13)
                            │  daemon thread receives → main thread runs bpy serially → auto undo_push
                            ▼
                    handlers/<category>.py: the actual bpy code

Fat add-on, thin server: all bpy logic lives in the add-on; the server only validates parameters and forwards. Tool names match one-to-one on both sides and a parity test keeps them in sync.

Tool catalog (17 categories, 159 tools)

Full signatures are in docs/tools.md (generated by dump-tools).

Category Count Tools
Scene & Objects 16 get_scene_info list_objects get_object_info create_primitive delete_object duplicate_object set_transform rename_object set_parent set_visibility select_objects manage_collection join_objects apply_transforms set_origin set_custom_property
Materials 9 list_materials get_material_info create_material assign_material set_principled_inputs set_material_settings add_image_texture create_pbr_material delete_material
Shader Nodes 10 list_shader_nodes add_shader_node remove_shader_node set_node_input set_node_property link_nodes unlink_nodes set_color_ramp build_node_tree get_node_types
Lights 6 list_lights get_light_info create_light set_light point_light_at set_world_lighting
Modifiers 8 list_modifier_types list_modifiers get_modifier_settings add_modifier set_modifier remove_modifier apply_modifier move_modifier
Animation 15 get_animation_info set_frame_range set_current_frame insert_keyframe insert_keyframes_batch delete_keyframe list_keyframes set_interpolation add_fcurve_modifier assign_action nla_push_down add_nla_strip bake_animation list_shape_keys set_shape_key
Geometry Nodes 11 list_node_groups create_geometry_nodes get_node_tree add_geometry_node remove_geometry_node link_geometry_nodes unlink_geometry_nodes set_geometry_node_input add_group_socket set_gn_modifier_input build_geometry_node_tree
Camera 7 list_cameras get_camera_info create_camera set_camera set_active_camera point_camera_at frame_objects
Render 7 get_render_settings list_render_engines set_render_settings set_color_management render_image render_animation viewport_screenshot
Import / Export 5 import_file export_file append_from_blend save_blend open_blend
UV & Texture 10 list_uv_maps add_uv_map remove_uv_map unwrap_uv pack_uv_islands mark_seams create_image bake_texture save_image list_images
Batch 8 batch_transform batch_rename batch_apply_material batch_add_modifier batch_set_property batch_delete distribute_objects randomize_transform
Assets 8 polyhaven_categories polyhaven_search polyhaven_download sketchfab_search sketchfab_download list_asset_libraries search_local_assets import_local_asset
Rigging 12 create_armature list_bones add_bone set_bone remove_bone parent_to_armature add_bone_constraint set_pose reset_pose set_vertex_group_weights add_rigify_metarig generate_rigify_rig
Rig Diagnostics 7 check_rig check_bone_hierarchy check_bone_naming find_unweighted_vertices get_bone_influence list_constraint_issues normalize_weights
Utilities 13 execute_code get_blender_info get_api_docs undo redo purge_orphans set_units set_cursor measure_distance get_bounding_box ray_cast check_mesh mesh_cleanup
Workflows 7 setup_three_point_lighting setup_studio_scene turntable_animation quick_product_render material_from_texture_folder scatter_objects export_for_game

A few capabilities worth calling out:

  • Whole node trees in one call: build_node_tree / build_geometry_node_tree take nodes=[{type,name,location,inputs,properties}] and links=[...] and build the entire tree at once, with no per-node round trips.
  • PBR materials: create_pbr_material builds a material from a set of texture paths; material_from_texture_folder scans a folder and recognises basecolor / roughness / metallic / normal / height / ao by filename.
  • Import / export formats: obj / fbx / gltf / glb / usd / usda / usdc / stl / ply / abc / blend, detected by extension, with options passed straight to the Blender operator. export_for_game duplicates → applies modifiers → triangulates → scales → exports.
  • Assets: Poly Haven HDRIs are wired into world lighting after download, textures become PBR materials, models are imported directly. Sketchfab needs an API token. Local asset libraries can be searched by type / keyword and imported.
  • Rigging: build armatures from scratch, add constraints, pose, write vertex-group weights; Rigify metarigs (human / quadruped / cat / wolf / horse / shark / bird) and generation; check_rig checks zero-length bones, multiple roots, unweighted vertices, un-normalised weights, unapplied scale, missing constraint targets, and asymmetric naming in one pass.
  • Baking: bake_texture bakes DIFFUSE / NORMAL / AO / ROUGHNESS / EMIT / COMBINED and more with Cycles, including selected-to-active.
  • Camera framing: frame_objects backs the camera off along its current direction until the targets just fit; point_camera_at / point_light_at aim at an object or coordinate.
  • Geometry queries: ray_cast, measure_distance, get_bounding_box, check_mesh (non-manifold, loose vertices, degenerate faces, and so on).

Installation

Prerequisites: Blender 5.2 LTS and uv.

git clone <this repo> blender_mcp && cd blender_mcp
uv sync
uv run blender-mcp-pro install-addon

install-addon links addon/blender_mcp_pro into Blender's user extensions directory, then enables the extension with headless Blender and saves preferences.

Platform Default Blender lookup Extensions directory Link type
macOS /Applications/Blender.app ~/Library/Application Support/Blender/5.2/extensions/user_default symlink
Windows C:\Program Files\Blender Foundation\Blender 5.2\blender.exe %APPDATA%\Blender Foundation\Blender\5.2\extensions\user_default symlink; falls back to a directory junction when symlinks are not permitted (no admin needed)
Linux blender on PATH, /usr/bin, /snap/bin ~/.config/blender/5.2/extensions/user_default symlink
  • Blender installed elsewhere: set BLENDER_MCP_BLENDER=<blender executable> first; likewise BLENDER_MCP_EXT_DIR for the extensions directory.
  • Prefer a copy over a link: install-addon --copy (re-run after editing the add-on source).
  • If a GUI Blender is open during installation, it will overwrite the preferences with its in-memory copy on exit. Confirm once more in the running Blender: Edit ▸ Preferences ▸ Add-ons, search "MCP Pro", tick it.
  • Once enabled the server starts automatically. Press N in the 3D viewport; the "MCP Pro" panel shows status, manual Start / Stop, and the port.

Connect to Claude Code

claude mcp add --scope user blender-pro -- uv --directory <absolute repo path> run blender-mcp-pro serve
claude mcp list        # expect: blender-pro … Connected

Windows example:

claude mcp add --scope user blender-pro -- uv --directory C:\work\blender_mcp run blender-mcp-pro serve

Other MCP clients (Cursor, Claude Desktop, and so on) use the same stdio command: uv --directory <repo> run blender-mcp-pro serve.

Optional environment variables: BLENDER_MCP_HOST / BLENDER_MCP_PORT (default 127.0.0.1 / 9877), SKETCHFAB_API_TOKEN.

Uninstall

uv run blender-mcp-pro uninstall-addon
claude mcp remove blender-pro -s user

Usage examples

With a GUI Blender open, just tell Claude Code:

  • "What's in the scene?" → get_scene_info / list_objects
  • "Make a 2 m tall cylinder with a brushed-metal material" → create_primitive + create_material + set_principled_inputs
  • "Three-point light this object and render a 1080p product shot" → quick_product_render, or setup_three_point_lighting + frame_objects + render_image
  • "Grab a 2k indoor HDRI from Poly Haven for the environment" → polyhaven_search + polyhaven_download
  • "Turn the textures in textures/wood/ into a material and put it on the table" → material_from_texture_folder
  • "Add a Rigify humanoid rig to the character and check it" → add_rigify_metarig + generate_rigify_rig + check_rig
  • "Export the selection as a game-ready GLB" → export_for_game
  • "Build a blocky Gundam out of bmesh" → execute_code (any bpy script), then frame_objects + render_image to look at it

Conventions

  • Location / rotation / scale are [x, y, z]; rotation is an Euler in radians. Colours are [r, g, b] or [r, g, b, a] in 0–1.
  • Any tool that accepts objects takes a list of names, or {"pattern": "Cube*"} / {"collection": "Props"} / {"type": "MESH"} / {"selected": true}.
  • When an object / material / node / socket is not found, the error lists candidate names.
  • Every write is undoable with Ctrl+Z in Blender; read-only tools stay out of the undo stack.
  • Principled BSDF sockets use the 5.2 names: Base Color, Metallic, Roughness, IOR, Alpha, Emission Color, Emission Strength, Specular IOR Level, …
  • execute_code has bpy / bmesh / mathutils / Vector / math preloaded; return_var returns a variable.
  • Render and download caches live in ~/.cache/blender-mcp-pro/ (renders/ hdris/ textures/ models/ sketchfab/) and can be cleared at any time.

Development and testing

uv run pytest -q                                   # 154 tests; integration tests spawn headless Blender automatically
BLENDER_MCP_ONLINE_TESTS=1 uv run pytest tests/test_assets.py   # also runs the Poly Haven online tests
uv run blender-mcp-pro dump-tools > docs/tools.md  # regenerate the tool catalog
  • Three test layers: protocol unit tests (fake Blender), handler integration tests (headless Blender, --factory-startup), and MCP stdio end-to-end (real MCP client → server → headless Blender).
  • Changed the add-on: F3 → "Reload Scripts" in Blender (takes effect immediately with a symlink / junction install).
  • Changed the server: restart it from Claude Code with /mcp.
  • Adding a tool: @command("name") in addon/blender_mcp_pro/handlers/<category>.py plus @mcp.tool() in src/blender_mcp_pro/tools/<category>.py; tests/test_parity.py keeps the names in sync.
  • Handler modules must not call bpy at module top level (the parity test loads the add-on with a fake bpy); use it inside function bodies only.

Known limitations

  • viewport_screenshot and undo / redo need a GUI Blender; headless mode raises a clear error.
  • Whether EEVEE renders in headless mode depends on the GPU context; tests pin WORKBENCH. In the GUI both EEVEE and Cycles work.
  • Sketchfab downloads need an API token: Preferences ▸ Add-ons ▸ Blender MCP Pro, or the SKETCHFAB_API_TOKEN environment variable.
  • 5.2 LTS only; not compatible with 4.x.
  • The schemas of 159 tools take up some context; if it feels slow, trimming by category is a possible follow-up.

Documentation

The detailed docs are currently in Chinese.

License

MIT

About

Local MCP server + Blender 5.2 extension: 159 tools to drive Blender from Claude Code

Resources

Stars

6 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages