blend-ai tool reference: 175 Blender MCP tools

Animation 8

create_animation_path

create_animation_path(object_name: str, path_object: str)

Make an object follow a path (curve) using a Follow Path constraint.

object_name	Name of the object to animate along the path.
path_object	Name of the curve object to use as the path.

Returns Confirmation dict with constraint details.

insert_keyframe

insert_keyframe(object_name: str, data_path: str, frame: int, value: Any = None)

Insert a keyframe on an object property at a specific frame.

object_name	Name of the object.
data_path	Property to keyframe. Must be one of: location, rotation_euler, rotation_quaternion, scale, or indexed variants like location[0].
frame	Frame number to insert the keyframe at.
value	Optional value to set before inserting the keyframe.

Returns Confirmation dict with keyframe details.

list_keyframes

list_keyframes(object_name: str)

List all keyframes on an object.

object_name	Name of the object.

Returns List of dicts with data_path, frame, and value for each keyframe.

set_frame

set_frame(frame: int)

Set the current frame in the timeline.

frame	Frame number to set as current.

Returns Confirmation dict with the new current frame.

set_frame_range

set_frame_range(start: int, end: int)

Set the start and end frames of the scene timeline.

start	Start frame number.
end	End frame number. Must be greater than start.

Returns Confirmation dict with the new frame range.

Armature & Rigging 6

add_bone

add_bone(armature_name: str, bone_name: str, head: list[float] | tuple[float, ...] = (0, 0, 0), tail: list[float] | tuple[float, ...] = (0, 0, 1), parent_bone: str = '')

Add a bone to an armature. Enters edit mode automatically.

armature_name	Name of the armature object.
bone_name	Name for the new bone.
head	XYZ position of the bone head (root). Defaults to (0, 0, 0).
tail	XYZ position of the bone tail (tip). Defaults to (0, 0, 1).
parent_bone	Optional name of the parent bone for hierarchy.

Returns Dict with the created bone's name, head, and tail positions.

add_constraint

add_constraint(object_name: str, bone_name: str = '', constraint_type: str = '', properties: dict[str, Any] | None = None)

Add a constraint to an object or bone.

object_name	Name of the object (armature for bone constraints).
bone_name	Name of the bone (empty string for object-level constraints).
constraint_type	Constraint type. One of: IK, COPY_ROTATION, COPY_LOCATION, COPY_SCALE, COPY_TRANSFORMS, TRACK_TO, DAMPED_TRACK, LOCKED_TRACK, LIMIT_ROTATION, LIMIT_LOCATION, LIMIT_SCALE, STRETCH_TO, FLOOR, CLAMP_TO, TRANSFORM, MAINTAIN_VOLUME, CHILD_OF, PIVOT, ARMATURE.
properties	Optional dict of constraint properties to set (e.g., target, subtarget, chain_count, influence, etc.).

Returns Dict with the created constraint's name and type.

create_armature

create_armature(name: str = 'Armature', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a new armature object.

name	Name for the armature. Defaults to "Armature".
location	XYZ position for the armature. Defaults to origin.

Returns Dict with the created armature's name and location.

mesh_name	Name of the mesh object to parent.
armature_name	Name of the armature object.
type	Parenting method. One of: ARMATURE_AUTO (automatic weights), ARMATURE_NAME (by bone names), ARMATURE_ENVELOPE (by envelope).

set_bone_property

set_bone_property(armature_name: str, bone_name: str, property: str, value: Any)

Set a property on a bone in an armature.

armature_name	Name of the armature object.
bone_name	Name of the bone.
property	Property to set. One of: roll, length, use_connect, use_deform, envelope_distance, head_radius, tail_radius, use_inherit_rotation, use_local_location.
value	Value to set the property to.

Returns Confirmation dict with bone name, property, and new value.

set_pose

set_pose(armature_name: str, bone_name: str, location: list[float] | tuple[float, ...] | None = None, rotation: list[float] | tuple[float, ...] | None = None, scale: list[float] | tuple[float, ...] | None = None)

Set the pose of a bone in an armature.

armature_name	Name of the armature object.
bone_name	Name of the bone to pose.
location	Optional XYZ location offset for the bone.
rotation	Optional XYZ Euler rotation in radians.
scale	Optional XYZ scale.

Returns Confirmation dict with the bone's new pose values.

Bool Tool 4

booltool_auto_difference

booltool_auto_difference(object_name: str, target_name: str)

Auto boolean difference: subtract the target object from the main object. The target object is used as a cutter and removed after the operation. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

object_name	Name of the object to cut from.
target_name	Name of the cutter object (will be removed).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_intersect

booltool_auto_intersect(object_name: str, target_name: str)

Auto boolean intersect: keep only the overlapping volume of two objects. The target object is removed after the operation. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

object_name	Name of the main object.
target_name	Name of the intersecting object (will be removed).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_slice

booltool_auto_slice(object_name: str, target_name: str)

Auto boolean slice: split the main object using the target as a cutter. Creates two separate pieces from the intersection. The target object is removed after the operation. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

object_name	Name of the object to slice.
target_name	Name of the cutter object (will be removed).

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

booltool_auto_union

booltool_auto_union(object_name: str, target_name: str)

Auto boolean union: merge two mesh objects into one. The target object is consumed and joined into the main object. This is useful for permanently joining meshes so parts don't float away from their bodies. Uses Bool Tool extension if installed, otherwise falls back to native boolean modifier (a warning will be included in the response).

object_name	Name of the main object to keep.
target_name	Name of the object to merge into the main object.

Returns Confirmation dict with operation details. May include a 'warning' field if Bool Tool is not available and native fallback was used.

Camera 6

capture_viewport

capture_viewport(filepath: str = '', width: int = 1920, height: int = 1080)

Render the viewport to a file or return as base64.

filepath	Optional absolute path for output image. If empty, returns base64-encoded image.
width	Render width in pixels, default 1920.
height	Render height in pixels, default 1080.

Returns Dict with filepath or base64 image data.

create_camera

create_camera(name: str = 'Camera', location: list = [0, 0, 0], rotation: list = [0, 0, 0], lens: float = 50.0)

Create a new camera in the scene.

name	Name for the camera, default "Camera".
location	XYZ location as [x, y, z], default [0, 0, 0].
rotation	XYZ Euler rotation in radians as [x, y, z], default [0, 0, 0].
lens	Focal length in mm, default 50.

Returns Confirmation dict with camera name and properties.

point_camera_at

point_camera_at(camera_name: str, target: str = '', location: list | None = None)

Point a camera at an object or a specific location using a Track To constraint.

camera_name	Name of the camera object.
target	Name of the target object to point at. Mutually exclusive with location.
location	XYZ location to point at as [x, y, z]. Mutually exclusive with target.

Returns Confirmation dict.

set_active_camera

set_active_camera(name: str)

Set the active scene camera.

name	Name of the camera object to make active.

Returns Confirmation dict.

set_camera_from_view

set_camera_from_view()

Match the active camera to the current 3D viewport view.

Returns Confirmation dict with the camera's new location and rotation.

set_camera_property

set_camera_property(name: str, property: str, value: Any)

Set a property on a camera.

name	Name of the camera object.
property	Property to set. One of: lens, clip_start, clip_end, sensor_width, sensor_height, dof.use_dof, dof.focus_distance, dof.aperture_fstop, ortho_scale, shift_x, shift_y, type, sensor_fit.
value	The value to set.

Returns Confirmation dict.

Code Execution 1

execute_blender_code

execute_blender_code(code: str)

Execute Python code inside Blender's sandboxed environment. The code runs in a restricted sandbox that blocks dangerous imports (os, subprocess, socket, etc.) and dangerous builtins (exec, eval, open). Safe Blender imports (bpy, bmesh, mathutils, math, json) are allowed.

code	Python code to execute. bpy is available but must be imported.

Returns Dict with 'output' (captured stdout) and 'success' boolean.

Collections 4

create_collection

create_collection(name: str, parent: str = '')

Create a new collection, optionally nested under a parent collection.

name	Name for the new collection.
parent	Optional name of parent collection to nest under. Empty string uses the scene's root collection.

Returns Dict with the created collection's name and parent.

delete_collection

delete_collection(name: str, delete_objects: bool = False)

Delete a collection.

name	Name of the collection to delete.
delete_objects	If True, also delete all objects in the collection. If False, objects are unlinked but kept in the scene.

Returns Confirmation dict.

move_to_collection

move_to_collection(object_names: list[str], collection_name: str)

Move objects to a collection, unlinking them from their current collections.

object_names	List of object names to move.
collection_name	Name of the destination collection.

Returns Dict with the moved objects and destination collection.

set_collection_visibility

set_collection_visibility(name: str, visible: bool, viewport: bool = True, render: bool = True)

Set collection visibility in viewport and/or render.

name	Name of the collection.
visible	Whether the collection should be visible.
viewport	Apply visibility change to viewport. Defaults to True.
render	Apply visibility change to render. Defaults to True.

Returns Confirmation dict with visibility state.

Curves 10

add_curve_point

add_curve_point(curve_name: str, location: list[float] | tuple[float, ...] = (0, 0, 0), handle_type: str = 'AUTO')

Add a control point to an existing curve.

curve_name	Name of the curve object to add a point to.
location	3D location for the new point as (x, y, z).
handle_type	Handle type - AUTO, VECTOR, ALIGNED, or FREE.

Returns Dict with curve name and new point count.

convert_curve_to_mesh

convert_curve_to_mesh(curve_name: str)

Convert a curve object to a mesh object.

curve_name	Name of the curve object to convert.

Returns Dict with the converted object name.

create_curve

create_curve(type: str = 'BEZIER', name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a new curve object.

type	Curve type - BEZIER, NURBS, or PATH.
name	Optional name for the curve object.
location	3D location as (x, y, z).

Returns Dict with created curve name and type.

create_text

create_text(text: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), size: float = 1.0, font: str = '')

Create a 3D text object.

text	The text string to display.
name	Optional name for the text object.
location	3D location as (x, y, z).
size	Font size.
font	Optional path to a font file. Uses default Blender font if empty.

Returns Dict with created text object name.

set_curve_property

set_curve_property(curve_name: str, property: str, value: Any)

Set a property on a curve object.

curve_name	Name of the curve object.
property	Property to set - resolution_u, fill_mode, bevel_depth, bevel_resolution, extrude, twist_mode, or use_fill_caps.
value	Value to set. Type depends on property.

Returns Confirmation dict with property name and new value.

set_handle_type

set_handle_type(curve_name: str, handle_type: str = 'AUTO')

Set the handle type for all control points of a curve.

curve_name	Name of the curve object.
handle_type	Handle type - AUTO, VECTOR, ALIGNED, or FREE_ALIGN.

Returns Dict with confirmation of handle type change.

smooth_curve

smooth_curve(curve_name: str)

Smooth the control points of a curve.

curve_name	Name of the curve object.

Returns Dict with confirmation of smoothing.

subdivide_curve

subdivide_curve(curve_name: str, number_cuts: int = 1)

Subdivide a curve by adding control points between existing ones.

curve_name	Name of the curve object.
number_cuts	Number of cuts to make (1-100).

Returns Dict with confirmation of subdivision.

switch_curve_direction

switch_curve_direction(curve_name: str)

Switch the direction of a curve's splines.

curve_name	Name of the curve object.

Returns Dict with confirmation of direction switch.

toggle_cyclic

toggle_cyclic(curve_name: str)

Toggle the cyclic (closed loop) state of a curve.

curve_name	Name of the curve object.

Returns Dict with confirmation of cyclic toggle.

File I/O 5

export_file

export_file(filepath: str, type: str = '', selected_only: bool = False)

Export scene or selected objects to a 3D file. Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, Alembic (ABC), Collada (DAE), SVG, and X3D formats.

filepath	Absolute path for the export file.
type	Optional format override. Auto-detected from extension if empty.
selected_only	If True, export only selected objects. Defaults to False.

Returns Dict with exported file path and format.

import_file

import_file(filepath: str, type: str = '')

Import a 3D file into Blender. Supports FBX, OBJ, GLTF/GLB, USD, STL, PLY, Alembic (ABC), Collada (DAE), SVG, and X3D formats. Auto-detects format from file extension if type is empty.

filepath	Absolute path to the file to import. Must exist.
type	Optional format override. One of: FBX, OBJ, GLTF, USD, STL, PLY, ABC, DAE, SVG, X3D. Auto-detected from extension if empty.

Returns Dict with imported file path and format.

list_recent_files

list_recent_files()

List recently opened files from Blender preferences.

Returns List of file path strings.

open_file

open_file(filepath: str)

Open a .blend file.

filepath	Absolute path to the .blend file. Must exist.

Returns Dict with the opened file path.

save_file

save_file(filepath: str = '')

Save the current Blender file. If filepath is empty, saves to the current file path (overwrite). If filepath is provided, performs a "Save As" to the given path.

filepath	Optional absolute path to save as. Must have .blend extension. Empty string saves to current file.

Returns Dict with the saved file path.

Geometry Nodes 5

add_geometry_node

add_geometry_node(modifier_name: str, node_type: str, location: list[float] | tuple[float, ...] = (0, 0))

Add a node to a geometry nodes modifier's node group.

modifier_name	Name of the geometry nodes modifier (used to find the node group).
node_type	Blender node type identifier, e.g. GeometryNodeMeshCube, GeometryNodeSetPosition, GeometryNodeTransform, ShaderNodeMath, GeometryNodeJoinGeometry, etc.
location	XY position for the node in the node editor. Defaults to (0, 0).

Returns Dict with the created node's name and type.

connect_geometry_nodes

connect_geometry_nodes(modifier_name: str, from_node: str, from_socket: int, to_node: str, to_socket: int)

Connect two nodes in a geometry nodes modifier's node group.

modifier_name	Name of the geometry nodes modifier.
from_node	Name of the source node.
from_socket	Index of the output socket on the source node.
to_node	Name of the destination node.
to_socket	Index of the input socket on the destination node.

Returns Confirmation dict with connection details.

create_geometry_nodes

create_geometry_nodes(object_name: str, name: str = 'GeometryNodes')

Create a Geometry Nodes modifier on an object.

object_name	Name of the object to add the modifier to.
name	Name for the geometry nodes modifier. Defaults to "GeometryNodes".

Returns Dict with modifier name and node group name.

list_geometry_node_inputs

list_geometry_node_inputs(object_name: str, modifier_name: str)

List all available inputs on a geometry nodes modifier.

object_name	Name of the object with the modifier.
modifier_name	Name of the geometry nodes modifier.

Returns List of dicts with input name, type, and current value.

set_geometry_node_input

set_geometry_node_input(object_name: str, modifier_name: str, input_name: str, value: Any)

Set an input value on a geometry nodes modifier.

object_name	Name of the object with the modifier.
modifier_name	Name of the geometry nodes modifier.
input_name	Name of the input socket to set (as shown in the modifier panel).
value	The value to set. Type depends on the input (float, int, vector, etc.).

Returns Confirmation dict with the input name and new value.

Grease Pencil 5

add_annotation_layer

add_annotation_layer(annotation_name: str, layer_name: str)

Add a layer to an annotation. Layers organize annotation strokes. Each layer can have its own blend mode, opacity, and color.

annotation_name	Name of the annotation data block.
layer_name	Name for the new layer.

Returns Confirmation dict with annotation and layer names.

add_annotation_stroke

add_annotation_stroke(annotation_name: str, layer_name: str, points: list[list[float]], pressure: float = 1.0)

Add a stroke to an annotation layer. Creates a new stroke with the given points on the specified layer. Note: AnnotationStroke does not support per-point strength/opacity.

annotation_name	Name of the annotation data block.
layer_name	Name of the layer to add the stroke to.
points	List of XYZ coordinates, e.g. [[0,0,0], [1,1,0], [2,0,0]]. Maximum 10000 points.
pressure	Pen pressure for all points. Range: 0.0-1.0.

Returns Confirmation dict with point count.

create_annotation

create_annotation(name: str = '')

Create a new annotation data block. Annotations are viewport overlays used for drawing marks, notes, and guides. Unlike Grease Pencil objects, annotations are not positioned in 3D space.

name	Optional name for the annotation. Auto-generated if empty.

Returns Dict with the created annotation's name.

remove_annotation_layer

remove_annotation_layer(annotation_name: str, layer_name: str)

Remove a layer from an annotation.

annotation_name	Name of the annotation data block.
layer_name	Name of the layer to remove.

Returns Confirmation dict.

set_annotation_stroke_property

set_annotation_stroke_property(annotation_name: str, layer_name: str, stroke_index: int, property: str, value: Any)

Set a property on an annotation stroke.

annotation_name	Name of the annotation data block.
layer_name	Name of the layer containing the stroke.
stroke_index	Index of the stroke in the layer (0-based).
property	Property to set. One of: line_width, material_index, display_mode.
value	The value to set.

Returns Confirmation dict.

Lighting 7

create_light

create_light(type: str, name: str = '', location: list = [0, 0, 0], energy: float = 1000.0, color: list = [1.0, 1.0, 1.0])

Create a new light in the scene.

type	Light type. One of: POINT, SUN, SPOT, AREA.
name	Optional name for the light.
location	XYZ location as [x, y, z], default [0, 0, 0].
energy	Light energy/power, default 1000.
color	RGB color as [r, g, b], default [1.0, 1.0, 1.0].

Returns Confirmation dict with light name and properties.

create_light_rig

create_light_rig(type: str, target: str = '', intensity: float = 1000.0)

Create a pre-built lighting rig (multiple lights arranged for common setups).

type	Rig type. One of: THREE_POINT, STUDIO, RIM, OUTDOOR.
target	Optional name of the object the rig should point at.
intensity	Overall intensity of the lights, default 1000.

Returns Confirmation dict with names of all created lights.

delete_light

delete_light(name: str)

Delete a light object from the scene.

name	Name of the light object to delete.

Returns Confirmation dict.

list_lights

list_lights()

List all light objects in the scene.

Returns List of dicts with light name, type, energy, color, and location.

set_light_property

set_light_property(name: str, property: str, value: Any)

Set a property on a light object.

name	Name of the light object.
property	Property to set. One of: energy, color, shadow_soft_size, spot_size, spot_blend, area_size, area_size_y, use_shadow, angle, specular_factor, diffuse_factor, volume_factor.
value	The value to set. Type depends on the property.

Returns Confirmation dict.

set_shadow_settings

set_shadow_settings(name: str, use_shadow: bool = True, shadow_soft_size: float = 0.25)

Configure shadow settings for a light.

name	Name of the light object.
use_shadow	Whether to enable shadows, default True.
shadow_soft_size	Soft shadow radius, default 0.25.

Returns Confirmation dict.

set_world_background

set_world_background(color: list | None = None, hdri_path: str | None = None, strength: float = 1.0)

Set the world background to a solid color or HDRI environment map.

color	RGB color as [r, g, b] for solid background. Mutually exclusive with hdri_path.
hdri_path	Absolute path to an HDRI image file. Mutually exclusive with color.
strength	Background strength/intensity, default 1.0.

Returns Confirmation dict.

Materials & Shaders 25

add_color_ramp_element

add_color_ramp_element(material_name: str, node_name: str, position: float, color: list)

Add a colour stop to a ColorRamp (ShaderNodeValToRGB) node. A new ramp starts with two stops, black at 0.0 and white at 1.0. Add stops to shape a gradient: fire needs dark red, orange, yellow, white bunched toward the top; rust needs a hard break between metal and oxide.

material_name	Name of the material.
node_name	Name of the ColorRamp node.
position	Stop position along the ramp, 0.0 to 1.0.
color	RGB or RGBA color, components 0.0 to 1.0. RGB gains alpha 1.0.

Returns Dict with the new element's index, position, and color.

add_shader_node

add_shader_node(material_name: str, node_type: str, location: list = [0, 0])

Add a shader node to a material's node tree.

material_name	Name of the material.
node_type	Blender shader node type (e.g. ShaderNodeBsdfPrincipled).
location	Node location as [x, y], default [0, 0].

Returns Dict with material, node_name, and node_type.

add_texture_node

add_texture_node(material_name: str, image_path: str, label: str = 'Image Texture')

Add an image texture node to a material and connect it to the Principled BSDF Base Color.

material_name	Name of the material.
image_path	Absolute path to the image file. Must exist on disk.
label	Label for the texture node, default "Image Texture".

Returns Confirmation dict.

assign_material

assign_material(object_name: str, material_name: str)

Assign a material to an object.

object_name	Name of the target object.
material_name	Name of the material to assign.

Returns Confirmation dict.

connect_shader_nodes

connect_shader_nodes(material_name: str, from_node: str, from_socket: str, to_node: str, to_socket: str)

Connect two shader nodes in a material's node tree.

material_name	Name of the material.
from_node	Name of the source node.
from_socket	Name of the output socket on the source node.
to_node	Name of the destination node.
to_socket	Name of the input socket on the destination node.

Returns Confirmation dict.

create_material

create_material(name: str)

Create a new material with a Principled BSDF shader node.

name	Name for the new material.

Returns Confirmation dict with the created material name.

create_principled_material

create_principled_material(name: str, color: list = [0.8, 0.8, 0.8, 1.0], metallic: float = 0.0, roughness: float = 0.5, specular: float = 0.5, emission_strength: float = 0.0, emission_color: list = [1.0, 1.0, 1.0, 1.0], alpha: float = 1.0, transmission: float = 0.0, ior: float = 1.45)

Create a fully configured Principled BSDF material in one call.

name	Name for the new material.
color	Base color as RGBA list, default [0.8, 0.8, 0.8, 1.0].
metallic	Metallic value 0.0-1.0, default 0.0.
roughness	Roughness value 0.0-1.0, default 0.5.
specular	Specular IOR level 0.0-1.0, default 0.5.
emission_strength	Emission strength, default 0.0.
emission_color	Emission color as RGBA list, default [1.0, 1.0, 1.0, 1.0].
alpha	Alpha value 0.0-1.0, default 1.0.
transmission	Transmission weight 0.0-1.0, default 0.0.
ior	Index of refraction, default 1.45.

Returns Confirmation dict with material name and all set properties.

create_procedural_material

create_procedural_material(name: str, pattern: str, scale: float = 5.0, detail: float = 2.0, distortion: float = 0.0, roughness: float = 0.5, metallic: float = 0.0, colors: list | None = None, banded: bool = False, connect_to_bsdf: bool = True)

Build a complete procedural texture as a material, in one call. Prefer this over hand-wiring texture nodes. It creates the full graph — coordinates, mapping, the pattern's texture nodes, a tuned colour ramp, and the Principled BSDF — and returns the node names so you can adjust anything afterwards with set_shader_node_input or the colour ramp tools. Procedural beats image textures here: no files, no UV unwrap needed, and it stays sharp at any camera distance. Call list_procedural_patterns() to see what each pattern looks like.

name	Name for the new material.
pattern	One of the supported patterns, e.g. 'fire', 'wood', 'veins'.
scale	Feature size. Lower is bigger and broader, higher is finer and busier. 5.0 is a sensible default; try 1-3 for large forms and 20+ for fine detail.
detail	Fractal octaves, 0-15. Higher adds finer sub-detail at the cost of render time. Applies to noise, cloud, wood, marble, plasma and fire. The cellular patterns (voronoi, veins, scales, sparks), stripes, weave and gradient have no detail socket and ignore it.
distortion	Warps the pattern. Small values (0.5-2.0) make wood and marble look organic rather than machine-perfect. Applies to noise, cloud, stripes, wood, marble, plasma and fire. The cellular patterns, weave and gradient ignore it.
roughness	Surface roughness 0-1 for the Principled BSDF.
metallic	Metallic 0-1 for the Principled BSDF.
colors	Optional list of RGB or RGBA colours for the ramp, in order. Omit to use the pattern's own tuned palette.
banded	Use CONSTANT ramp interpolation, giving hard-edged bands instead of smooth blending. Turns noise into discrete regions: scale plates, cracked mud, cel shading.
connect_to_bsdf	Wire the result into the Principled BSDF base colour so the material renders immediately. Set False to leave the pattern subtree unconnected for manual wiring.

Returns Dict with the material name, the created node names, and ignored_params listing any arguments this pattern could not use.

create_raster_texture

create_raster_texture(name: str, pattern: str, size: int = 512, count: int = 12, seed: int = 0, foreground: list | None = None, background: list | None = None)

Generate an image texture for patterns shader nodes cannot express. Use this only for patterns that place discrete marks. Shader nodes evaluate a function per point and have no way to say "draw a glyph here, then another over there", so runes need real pixels. Everything else should go through create_procedural_material, which stays sharp at any resolution. The image is packed into the blend file. No file is written to disk.

name	Name for the generated image datablock.
pattern	A raster pattern. Currently 'runes'.
size	Pixel width and height, up to 2048. Cost grows with the square.
count	How many marks to stamp. 0 leaves a blank field.
seed	Change for a different arrangement; the same seed always reproduces the same image.
foreground	RGB or RGBA colour of the marks.
background	RGB or RGBA colour behind them.

Returns Dict with the image name, size, and mark count.

delete_material

delete_material(material_name: str)

Delete a material by name.

material_name	Name of the material to delete.

Returns Confirmation dict.

disconnect_shader_nodes

disconnect_shader_nodes(material_name: str, node_name: str, socket_name: str, is_input: bool = True)

Disconnect all links from a specific socket on a shader node.

material_name	Name of the material.
node_name	Name of the node.
socket_name	Name of the socket to disconnect.
is_input	If True, disconnect an input socket; otherwise an output socket.

Returns Confirmation dict.

duplicate_material

duplicate_material(material_name: str, new_name: str)

Duplicate a material with a new name.

material_name	Name of the material to duplicate.
new_name	Name for the duplicated material.

Returns Confirmation dict with the new material name.

get_color_ramp

get_color_ramp(material_name: str, node_name: str)

Read every stop on a ColorRamp node. Use this before editing to learn the current indices and positions, since add and move operations reorder stops.

material_name	Name of the material.
node_name	Name of the ColorRamp node.

Returns Dict with elements (index, position, color), interpolation, color_mode.

get_node_tree

get_node_tree(material_name: str)

Get the full node tree of a material (all nodes and links).

material_name	Name of the material.

Returns Dict with nodes list and links list.

list_materials

list_materials()

List all materials in the current Blender file.

Returns List of dicts with material name and user count.

list_procedural_patterns

list_procedural_patterns()

List every procedural pattern with a description of what it looks like. Read this before calling create_procedural_material so you pick a pattern that matches the surface you are trying to make.

Returns Dict with the sorted pattern names and a description of each.

remove_color_ramp_element

remove_color_ramp_element(material_name: str, node_name: str, index: int)

Remove a colour stop from a ColorRamp node. Blender requires at least one stop to remain; removing the last one fails.

material_name	Name of the material.
node_name	Name of the ColorRamp node.
index	Zero-based index of the stop to remove.

Returns Dict with the removed index and the remaining element count.

remove_shader_node

remove_shader_node(material_name: str, node_name: str)

Remove a shader node from a material's node tree.

material_name	Name of the material.
node_name	Name of the node to remove.

Returns Confirmation dict.

set_color_ramp_element

set_color_ramp_element(material_name: str, node_name: str, index: int, position: float | None = None, color: list | None = None)

Move or recolor an existing ColorRamp stop. At least one of position or color must be given. Moving a stop past a neighbour reorders the ramp, so indices may shift after this call — read the ramp back with get_color_ramp if you need certainty.

material_name	Name of the material.
node_name	Name of the ColorRamp node.
index	Zero-based index of the stop to edit.
position	New position, 0.0 to 1.0. Omit to leave unchanged.
color	New RGB or RGBA color. Omit to leave unchanged.

Returns Dict with the element's resulting position and color.

set_color_ramp_interpolation

set_color_ramp_interpolation(material_name: str, node_name: str, interpolation: str, color_mode: str = '')

Set how a ColorRamp blends between its stops. 'CONSTANT' gives hard-edged bands with no blending, which is what turns a noise or voronoi texture into discrete regions: scale plates, cracked mud, stylised cel shading. 'EASE' and 'B_SPLINE' give softer falloff than 'LINEAR'. Set color_mode to 'HSV' to sweep through hues between two stops rather than blending through grey.

material_name	Name of the material.
node_name	Name of the ColorRamp node.
interpolation	One of EASE, CARDINAL, LINEAR, B_SPLINE, CONSTANT.
color_mode	Optional. One of RGB, HSV, HSL. Omit to leave unchanged.

Returns Dict with the applied interpolation and color mode.

set_material_blend_mode

set_material_blend_mode(material_name: str, mode: str)

Set the blend mode of a material (EEVEE).

material_name	Name of the material.
mode	Blend mode. One of: OPAQUE, CLIP, HASHED, BLEND.

Returns Confirmation dict.

set_material_color

set_material_color(material_name: str, color: list)

Set the base color of a material's Principled BSDF node.

material_name	Name of the material.
color	RGBA color as a list of 4 floats (0.0-1.0). e.g. [1.0, 0.0, 0.0, 1.0] for red.

Returns Confirmation dict.

set_material_property

set_material_property(material_name: str, property: str, value: Any)

Set a property on a material's Principled BSDF node.

material_name	Name of the material.
property	Property to set. One of: metallic, roughness, specular_ior_level, emission_strength, alpha, transmission_weight, ior, coat_weight, coat_roughness, sheen_weight, sheen_roughness, anisotropic, anisotropic_rotation, subsurface_weight, emission_color.
value	The value to set. Float for most properties, list for color properties.

Returns Confirmation dict.

set_shader_node_input

set_shader_node_input(material_name: str, node_name: str, socket: str | int, value: float | bool | list)

Set the default value of an unconnected input socket on a shader node. This is how you dial in a procedural texture: Noise 'Scale' and 'Detail', Mapping 'Scale' and 'Rotation', a Principled BSDF 'Roughness', and so on. A socket that has a link into it ignores its default value, so disconnect it first if you want the default to take effect.

material_name	Name of the material.
node_name	Name of the node.
socket	Socket name, or a zero-based index. Use the index when names are ambiguous — a Math node has two inputs both called 'Value'.
value	A number, a boolean, or a 2-4 component list for vectors and colors (colors are RGBA).

Returns Dict with the node, socket, and the value that was applied.

set_shader_node_property

set_shader_node_property(material_name: str, node_name: str, property: str, value: str | float | bool)

Set a node-level property (not a socket) on a shader node. These are the dropdowns and checkboxes on the node body rather than its input sockets: Math 'operation', Mix 'blend_type', Voronoi 'feature' (use 'DISTANCE_TO_EDGE' for vein and crack patterns), Wave 'wave_type' and 'bands_direction', Noise 'noise_dimensions'.

material_name	Name of the material.
node_name	Name of the node.
property	Property name. Must be one of the allowed node properties.
value	String enum identifier, number, or boolean.

Returns Dict with the node, property, and the value that was applied.

Mesh Editing 16

dissolve_edges

dissolve_edges(object_name: str)

Dissolve all edges, merging adjacent faces. Simplifies topology by removing unnecessary edge loops while preserving the overall shape.

object_name	Name of the mesh object.

Returns Confirmation dict.

dissolve_faces

dissolve_faces(object_name: str)

Dissolve all faces, merging them into surrounding geometry. Removes faces while keeping the surrounding mesh structure intact. Cleaner than deleting faces which leaves holes.

object_name	Name of the mesh object.

Returns Confirmation dict.

dissolve_verts

dissolve_verts(object_name: str)

Dissolve all vertices, merging connected edges and faces. Removes vertices while preserving surrounding geometry.

object_name	Name of the mesh object.

Returns Confirmation dict.

fill_faces

fill_faces(object_name: str)

Fill selected edges with a face. Creates faces from a closed edge loop. Useful for closing gaps in meshes or capping open ends.

object_name	Name of the mesh object.

Returns Confirmation dict.

flip_normals

flip_normals(object_name: str)

Flip the direction of all face normals on a mesh. Reverses inside/outside of all faces. Use recalculate_normals instead if normals are inconsistent rather than uniformly wrong.

object_name	Name of the mesh object.

Returns Confirmation dict.

grid_fill

grid_fill(object_name: str, span: int = 1, offset: int = 0)

Fill a closed edge loop with a grid of quads. Creates a clean quad grid between edge loops. Better than fill_faces for maintaining good topology.

object_name	Name of the mesh object.
span	Number of grid columns. Range: 1-1000.
offset	Offset for the grid alignment. Range: 0-1000.

Returns Confirmation dict.

inset_faces

inset_faces(object_name: str, thickness: float = 0.1, depth: float = 0.0)

Inset all faces of a mesh, creating a border/frame around each face. Core hard-surface modeling operation for adding detail, panel lines, or preparing faces for extrusion.

object_name	Name of the mesh object.
thickness	Inset thickness (border width). Range: 0.0-10.0.
depth	Inset depth (positive=outward, negative=inward). Range: -10.0 to 10.0.

Returns Confirmation dict.

knife_project

knife_project(object_name: str, cutter_name: str)

Project a cutter object's outline onto a mesh to cut it. The cutter object (curve or mesh) is projected from the viewport onto the target mesh, cutting new edges into it.

object_name	Name of the mesh to cut into.
cutter_name	Name of the cutter object (curve or mesh) to project.

Returns Confirmation dict.

mark_seam

mark_seam(object_name: str, clear: bool = False)

Mark or clear UV seams on all edges of a mesh. UV seams guide the UV unwrapping process. Edges marked as seams define where the mesh is "cut" when unwrapped to 2D.

object_name	Name of the mesh object.
clear	If True, clear seams instead of marking them.

Returns Confirmation dict.

mark_sharp

mark_sharp(object_name: str, clear: bool = False)

Mark or clear sharp edges on a mesh. Sharp edges control auto-smooth shading. Edges marked as sharp will have a hard edge in the shading even with smooth shading enabled.

object_name	Name of the mesh object.
clear	If True, clear sharp marks instead of setting them.

Returns Confirmation dict.

quads_to_tris

quads_to_tris(object_name: str)

Convert all quad faces to triangles. Useful for game engine export or when triangulated geometry is required.

object_name	Name of the mesh object.

Returns Confirmation dict.

recalculate_normals

recalculate_normals(object_name: str, inside: bool = False)

Recalculate face normals to be consistent (all pointing outward or inward). Fixes meshes with flipped or inconsistent normals that cause shading artifacts.

object_name	Name of the mesh object.
inside	If True, normals point inward instead of outward.

Returns Confirmation dict.

select_linked

select_linked(object_name: str)

Select all geometry linked to the current selection. Expands selection to include all connected vertices, edges, and faces. Useful for isolating mesh islands or selecting connected components.

object_name	Name of the mesh object.

Returns Confirmation dict.

set_edge_crease

set_edge_crease(object_name: str, value: float = 1.0)

Set edge crease value on all edges for subdivision surface control. Crease values control how sharp edges remain when a Subdivision Surface modifier is applied. 0 = fully smooth, 1 = fully sharp.

object_name	Name of the mesh object.
value	Crease value. Range: -1.0 to 1.0.

Returns Confirmation dict.

spin_mesh

spin_mesh(object_name: str, angle: float = math.tau, steps: int = 12, axis: list[float] | tuple[float, ...] = (0, 0, 1), center: list[float] | tuple[float, ...] = (0, 0, 0))

Spin (lathe) mesh geometry around an axis. Creates rotational geometry by duplicating and rotating the selected geometry around a center point. Great for creating round shapes like vases, columns, or wheels.

object_name	Name of the mesh object.
angle	Total spin angle in radians. Range: -6.283 to 6.283 (full circle).
steps	Number of steps in the spin. Range: 1-1000.
axis	Spin axis as XYZ vector. Defaults to Z-up (0, 0, 1).
center	Center point for the spin as XYZ. Defaults to origin.

Returns Confirmation dict.

tris_to_quads

tris_to_quads(object_name: str)

Convert adjacent triangle pairs to quad faces where possible. Improves topology for subdivision and deformation. Not all triangles can be merged — only adjacent pairs with compatible angles.

object_name	Name of the mesh object.

Returns Confirmation dict.

Mesh Quality 1

analyze_mesh_quality

analyze_mesh_quality(object_name: str)

Analyze mesh topology quality and return a structured defect report. Checks for non-manifold edges, loose vertices, zero-area faces, duplicate vertices, and wire edges. Returns counts and sample indices (capped at 50 per category) for each defect type.

object_name	Name of the mesh object to analyze.

Returns Dict with vertex/edge/face counts, defect counts and sample indices, and an issues_found boolean.

Modeling 13

add_modifier

add_modifier(object_name: str, modifier_type: str, name: str = '')

Add a modifier to a mesh object (non-destructive workflow). TIP: For BOOLEAN type, consider using booltool_auto_union/difference/intersect/slice instead — they apply the boolean immediately and handle cutter cleanup automatically. Only use add_modifier with BOOLEAN when you want a non-destructive modifier stack.

object_name	Name of the object to add the modifier to.
modifier_type	Type of modifier. Must be one of: SUBSURF, MIRROR, ARRAY, BEVEL, BOOLEAN, SOLIDIFY, DECIMATE, REMESH, WIREFRAME, SHRINKWRAP, SMOOTH, EDGE_SPLIT, TRIANGULATE, WEIGHTED_NORMAL, SIMPLE_DEFORM, LATTICE, CURVE, CAST, WAVE, DISPLACE, SCREW, SKIN, MASK, WELD, CORRECTIVE_SMOOTH, LAPLACIAN_SMOOTH, SURFACE_DEFORM, MESH_DEFORM, HOOK.
name	Optional custom name for the modifier.

Returns Confirmation dict with modifier details.

apply_modifier

apply_modifier(object_name: str, modifier_name: str)

Apply a modifier to an object, making its effect permanent.

object_name	Name of the object.
modifier_name	Name of the modifier to apply.

Returns Confirmation dict.

bevel_edges

bevel_edges(object_name: str, width: float = 0.1, segments: int = 1)

Bevel all edges of a mesh.

object_name	Name of the mesh object.
width	Bevel width.
segments	Number of bevel segments. Range: 1-100.

Returns Confirmation dict.

boolean_operation

boolean_operation(object_name: str, target_name: str, operation: str = 'DIFFERENCE')

Perform a boolean operation between two objects using a modifier. NOTE: For destructive booleans, prefer the booltool_auto_* tools instead (booltool_auto_union, booltool_auto_difference, booltool_auto_intersect, booltool_auto_slice). They handle selection and cutter cleanup automatically. Use this tool only when you need a non-destructive boolean modifier workflow.

object_name	Name of the object to apply the boolean to.
target_name	Name of the target/cutter object.
operation	Boolean operation type. One of: UNION, DIFFERENCE, INTERSECT.

Returns Confirmation dict with operation details.

bridge_edge_loops

bridge_edge_loops(object_name: str, segments: int = 1, profile_shape_factor: float = 0.0)

Bridge two edge loops to create connecting geometry. Select two edge loops on a mesh before calling this. The operation creates faces connecting the two loops, useful for connecting separate mesh parts, creating holes between surfaces, or building tube-like geometry.

object_name	Name of the mesh object with selected edge loops.
segments	Number of segments in the bridge. Range: 1-1000.
profile_shape_factor	Shape of the bridge profile. Range: -1.0 to 1.0. 0.0 is straight, positive values bulge outward, negative inward.

Returns Confirmation dict with bridge details.

extrude_faces

extrude_faces(object_name: str, offset: float = 1.0)

Extrude all faces of a mesh along their normals.

object_name	Name of the mesh object.
offset	Extrusion distance along face normals.

Returns Confirmation dict.

loop_cut

loop_cut(object_name: str, cuts: int = 1)

Add loop cuts to a mesh object.

object_name	Name of the mesh object.
cuts	Number of loop cuts. Range: 1-100.

Returns Confirmation dict.

merge_vertices

merge_vertices(object_name: str, threshold: float = 0.0001)

Merge vertices by distance.

object_name	Name of the mesh object.
threshold	Maximum distance between vertices to merge. Range: 0.0-10.0.

Returns Confirmation dict with number of removed vertices.

remove_modifier

remove_modifier(object_name: str, modifier_name: str)

Remove a modifier from an object.

object_name	Name of the object.
modifier_name	Name of the modifier to remove.

Returns Confirmation dict.

separate_mesh

separate_mesh(object_name: str, type: str = 'SELECTED')

Separate a mesh into parts.

object_name	Name of the mesh object.
type	Separation method. One of: SELECTED, MATERIAL, LOOSE.

Returns Confirmation dict.

set_modifier_property

set_modifier_property(object_name: str, modifier_name: str, property: str, value: Any)

Set a property on a modifier (e.g., levels, count, offset, angle).

object_name	Name of the object.
modifier_name	Name of the modifier.
property	The modifier property to set (e.g., 'levels', 'count', 'width', 'segments', 'angle', 'offset', 'ratio', 'iterations').
value	The value to set.

Returns Confirmation dict with updated property.

set_smooth_shading

set_smooth_shading(object_name: str, smooth: bool = True)

Set smooth or flat shading on an object. TIP: For production use, prefer shade_auto_smooth which provides angle-based auto-smooth shading — it gives better results on hard-surface models by only smoothing faces within the angle threshold.

object_name	Name of the mesh object.
smooth	True for smooth shading, False for flat shading.

Returns Confirmation dict.

subdivide_mesh

subdivide_mesh(object_name: str, cuts: int = 1)

Subdivide a mesh.

object_name	Name of the mesh object to subdivide.
cuts	Number of cuts per edge. Range: 1-100.

Returns Confirmation dict.

Objects 15

convert_object

convert_object(object_name: str, target: str = 'MESH')

Convert an object to a different type.

object_name	Name of the object to convert.
target	Target type. One of: MESH, CURVE, SURFACE, META, FONT, CURVES, POINTCLOUD, GPENCIL.

Returns Confirmation dict.

create_object

create_object(type: str, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), scale: list[float] | tuple[float, ...] = (1, 1, 1))

Create a primitive object in the scene.

type	Primitive type. One of: CUBE, SPHERE, UV_SPHERE, ICO_SPHERE, CYLINDER, CONE, TORUS, PLANE, CIRCLE, MONKEY, EMPTY.
name	Optional name for the object. Auto-generated if empty.
location	XYZ position as a 3-element list/tuple. Defaults to origin.
rotation	XYZ Euler rotation in radians as a 3-element list/tuple.
scale	XYZ scale as a 3-element list/tuple. Defaults to (1,1,1).

Returns Dict with the created object's name, type, and location.

create_polygon_prism

create_polygon_prism(sides: int, radius: float = 1.0, depth: float = 2.0, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0), rotation: list[float] | tuple[float, ...] = (0, 0, 0), scale: list[float] | tuple[float, ...] = (1, 1, 1))

Create an N-sided regular prism (polygon-based cylinder). Useful for hex sockets, octagonal columns, triangular prisms, or any straight-sided geometry where a 32-sided round cylinder is the wrong primitive. For a hex socket cutter on an M3 button-head screw, use sides=6.

sides	Number of sides for the polygon base. Range: 3-64.
radius	Circumscribed radius (center to vertex). Must be > 0.
depth	Height of the prism along its Z axis. Must be > 0.
name	Optional name for the object. Auto-generated if empty.
location	XYZ position as a 3-element list/tuple. Defaults to origin.
rotation	XYZ Euler rotation in radians as a 3-element list/tuple.
scale	XYZ scale as a 3-element list/tuple. Defaults to (1,1,1).

Returns Dict with the created object's name, type, location, and sides.

create_threaded_shaft

create_threaded_shaft(diameter: float, length: float, pitch: float, thread_depth: float = 0.0, segments: int = 32, thread_runout: float = -1.0, name: str = '', location: list[float] | tuple[float, ...] = (0, 0, 0))

Create a cylindrical shaft with helical external threads. Produces a single mesh object — a threaded rod at the given diameter and length, with helical thread ridges following the specified pitch. Suitable for boolean-union onto a screw-head or direct use as a threaded fastener. Thread geometry: a 60-degree V profile swept along a Z-axis helix via the Screw modifier.

diameter	Major diameter of the shaft (outer thread peaks). Must be > 0.
length	Axial length of the shaft (under-head length, like real fastener spec). Must be > 0.
pitch	Distance between thread peaks along the axis. Must be > 0 and <= length.
thread_depth	Radial depth of the thread (major radius - minor radius). If 0 (default), auto-computed as pitch * 0.54.
segments	Rotational resolution of the helix (steps per revolution). Range: 3-256. Higher = smoother helix, more geometry.
thread_runout	Smooth (unthreaded) region at the top of the shaft. Defaults to 0 (full-length threads) — gives the strongest print because threads under the head form a continuous stress path. Leaving a smooth runout creates a thin-walled neck at minor_r that snaps under torque in FDM prints. Pass a positive value only if a head's deep hex socket would otherwise reach thread peaks.
name	Optional name for the object. Auto-generated if empty.
location	XYZ position of the shaft base as a 3-element list/tuple.

Returns Dict with the created object's name, diameter, length, pitch, and the number of thread iterations actually generated.

delete_object

delete_object(name: str)

Delete an object from the scene by name.

name	Name of the object to delete.

Returns Confirmation dict.

duplicate_object

duplicate_object(name: str, linked: bool = False)

Duplicate an object.

name	Name of the object to duplicate.
linked	If True, create a linked duplicate (shares mesh data). Defaults to False.

Returns Dict with the new object's name.

get_object_info

get_object_info(name: str)

Get detailed information about an object.

name	Name of the object.

Returns Dict with type, location, rotation, scale, modifiers, materials, parent, children, and visibility info.

join_objects

join_objects(names: list[str])

Join multiple mesh objects into one (keeps all geometry as-is). This merges objects into a single datablock without modifying geometry. The meshes remain separate inside the object (no boolean merge). TIP: If you want to truly fuse overlapping meshes into one solid shape, use booltool_auto_union instead — it performs a boolean union that merges the geometry and removes internal faces.

names	List of object names to join. The first name becomes the active object.

Returns Dict with the resulting joined object name.

list_objects

list_objects(type_filter: str = '')

List all objects in the scene, optionally filtered by type.

type_filter	Filter by object type (e.g., MESH, LIGHT, CAMERA, EMPTY). Empty string returns all objects.

Returns List of dicts with object name, type, and location.

make_single_user

make_single_user(object_name: str, object: bool = True, data: bool = True)

Make an object's data single-user (unlink shared datablocks).

object_name	Name of the object.
object	Make the object single-user. Defaults to True.
data	Make the object data (e.g., mesh) single-user. Defaults to True.

Returns Confirmation dict.

parent_objects

parent_objects(child: str, parent: str)

Set parent-child relationship between two objects.

child	Name of the child object.
parent	Name of the parent object.

Returns Confirmation dict.

rename_object

rename_object(old_name: str, new_name: str)

Rename an object.

old_name	Current name of the object.
new_name	New name for the object.

Returns Dict with old and new names.

select_objects

select_objects(names: list[str], deselect_others: bool = True)

Select objects by name.

names	List of object names to select.
deselect_others	If True, deselect all other objects first. Defaults to True.

Returns Dict with list of selected object names.

set_object_visibility

set_object_visibility(name: str, visible: bool, viewport: bool = True, render: bool = True)

Set object visibility in viewport and/or render.

name	Name of the object.
visible	Whether the object should be visible.
viewport	Apply visibility change to viewport. Defaults to True.
render	Apply visibility change to render. Defaults to True.

Returns Confirmation dict with visibility state.

shade_auto_smooth

shade_auto_smooth(object_name: str, angle: float = 0.523599)

Apply angle-based auto-smooth shading to an object. Smooths faces only where the angle between adjacent face normals is below the given threshold, giving clean results on hard-surface models.

object_name	Name of the mesh object.
angle	Auto-smooth angle threshold in radians (0.0 to pi). Defaults to ~30 degrees (0.523599 rad).

Returns Confirmation dict.

Physics 9

add_cloth_sim

add_cloth_sim(object_name: str, quality: int = 5, mass: float = 0.3)

Add a cloth physics simulation to an object.

object_name	Name of the mesh object.
quality	Simulation quality steps (1-80).
mass	Mass of the cloth in kg.

Returns Confirmation dict with cloth settings.

add_fluid_sim

add_fluid_sim(object_name: str, type: str = 'DOMAIN', domain_type: str = 'GAS')

Add a fluid physics simulation to an object.

object_name	Name of the object.
type	Fluid type - DOMAIN (container), FLOW (emitter), or EFFECTOR (obstacle).
domain_type	Domain simulation type - GAS (smoke/fire) or LIQUID. Only used when type is DOMAIN.

Returns Confirmation dict with fluid settings.

add_particle_system

add_particle_system(object_name: str, count: int = 1000, lifetime: float = 50.0, emit_from: str = 'FACE')

Add a particle system to an object.

object_name	Name of the mesh object.
count	Number of particles (max 1000000).
lifetime	Particle lifetime in frames.
emit_from	Emission source - VERT, FACE, or VOLUME.

Returns Confirmation dict with particle system settings.

add_rigid_body

add_rigid_body(object_name: str, type: str = 'ACTIVE', mass: float = 1.0, friction: float = 0.5, restitution: float = 0.0)

Add a rigid body physics simulation to an object.

object_name	Name of the object.
type	Rigid body type - ACTIVE (affected by physics) or PASSIVE (static collider).
mass	Mass of the object in kg.
friction	Surface friction coefficient (0.0-1.0).
restitution	Bounciness (0.0-1.0).

Returns Confirmation dict with rigid body settings.

bake_physics

bake_physics(object_name: str, physics_type: str = '')

Bake a physics simulation for an object.

object_name	Name of the object with physics.
physics_type	Optional physics type to bake. If empty, bakes all physics on the object.

Returns Confirmation dict.

delete_particle_system

delete_particle_system(object_name: str, particle_system_name: str = '')

Remove a particle system from an object.

object_name	Name of the object.
particle_system_name	Name of the particle system to remove. If empty, removes the first particle system.

Returns Confirmation dict.

set_particle_rendering

set_particle_rendering(object_name: str, render_type: str = 'PATH', instance_object: str = '', instance_collection: str = '')

Set rendering mode for an object's particle system.

object_name	Name of the object with a particle system.
render_type	Render type. One of: NONE, PATH, OBJECT, COLLECTION.
instance_object	Object to instance (when render_type is OBJECT).
instance_collection	Collection to instance (when render_type is COLLECTION).

Returns Confirmation dict.

set_particle_velocity

set_particle_velocity(object_name: str, normal: float = 1.0, tangent: float = 0.0, object_align_factor: list[float] | tuple[float, ...] = (0, 0, 0))

Set velocity settings for an object's particle system.

object_name	Name of the object with a particle system.
normal	Velocity along face normals.
tangent	Velocity along face tangents.
object_align_factor	XYZ velocity factors relative to the object. 3-element vector.

Returns Confirmation dict.

set_physics_property

set_physics_property(object_name: str, physics_type: str, property: str, value: Any)

Set a property on an existing physics simulation.

object_name	Name of the object with the physics simulation.
physics_type	Physics type - RIGID_BODY, CLOTH, FLUID, or PARTICLE_SYSTEM.
property	Property name to set (depends on physics type).
value	Value to set.

Returns Confirmation dict with property name and new value.

Rendering 7

render_animation

render_animation(filepath: str = '/tmp/render_', format: str = 'PNG')

Render the animation sequence to image files.

filepath	Output file path prefix for the rendered frames. Each frame will be saved with a frame number suffix.
format	Output format. One of: PNG, JPEG, OPEN_EXR, TIFF, BMP.

Returns Confirmation dict with output details.

render_image

render_image(filepath: str = '/tmp/render.png')

Render the current scene to an image file.

filepath	Output file path for the rendered image. Must be an absolute path with a valid image extension (.png, .jpg, .exr, .tiff, .bmp).

Returns Confirmation dict with the output file path.

set_eevee_light_path

set_eevee_light_path(diffuse_intensity: float | None = None, glossy_intensity: float | None = None, transmission_intensity: float | None = None)

Set EEVEE light path intensity controls (Blender 5.1+). Controls how strongly different light bounce types contribute to the final image. Only applies when render engine is BLENDER_EEVEE.

diffuse_intensity	Intensity multiplier for diffuse bounces. Range: 0.0-10.0.
glossy_intensity	Intensity multiplier for glossy/specular bounces. Range: 0.0-10.0.
transmission_intensity	Intensity multiplier for transmission bounces. Range: 0.0-10.0.

Returns Dict with the current light path intensity values.

set_output_format

set_output_format(format: str, filepath: str = '')

Set the render output format and optionally the output file path.

format	Output format. One of: PNG, JPEG, OPEN_EXR, TIFF, BMP.
filepath	Optional output file path. Must be an absolute path.

Returns Confirmation dict with the new output settings.

set_render_engine

set_render_engine(engine: str)

Set the render engine.

engine	Render engine to use. One of: BLENDER_EEVEE, CYCLES, BLENDER_WORKBENCH.

Returns Confirmation dict with the active render engine.

set_render_resolution

set_render_resolution(width: int, height: int, percentage: int = 100)

Set the render resolution.

width	Render width in pixels. Range: 1-8192.
height	Render height in pixels. Range: 1-8192.
percentage	Resolution percentage scale. Range: 1-100.

Returns Confirmation dict with the new resolution settings.

set_render_samples

set_render_samples(samples: int)

Set the number of render samples.

samples	Number of samples. Range: 1-10000.

Returns Confirmation dict with the new sample count.

Scene 6

create_scene

create_scene(name: str)

Create a new scene.

name	Name for the new scene.

Returns Confirmation dict with the created scene name.

delete_scene

delete_scene(name: str)

Delete a scene by name.

name	Name of the scene to delete. Cannot delete the last remaining scene.

Returns Confirmation dict.

get_scene_info

get_scene_info()

Get full scene information including object tree, hierarchy, counts, frame range, fps, and render engine. Returns a dict with scene name, object list with hierarchy, object type counts, frame range (start, end, current), fps, and active render engine.

list_scenes

list_scenes()

List all scenes in the current Blender file. Returns a list of dicts, each containing the scene name and object count.

set_scene_property

set_scene_property(property: str, value: Any)

Set a scene property such as frame_start, frame_end, frame_current, fps, unit_system, or render_engine.

property	The scene property to set. Must be one of: frame_start, frame_end, frame_current, frame_step, fps, unit_system, render_engine, use_gravity, gravity.
value	The value to set the property to. Type depends on the property.

Returns Confirmation dict with the property name and new value.

suggest_extensions

suggest_extensions(task_description: str = '')

Suggest helpful Blender extensions for a planned task. Analyzes the task description and recommends free Blender extensions that could improve the workflow. Already-installed extensions are excluded.

task_description	Description of the planned task. If empty, returns all extensions not currently installed.

Returns Dict with 'suggestions' list of recommended extensions and 'installed' list of already-installed extension IDs.

Sculpting 8

add_multires_modifier

add_multires_modifier(object_name: str, levels: int = 2)

Add a Multiresolution modifier for sculpting detail.

object_name	Name of the mesh object.
levels	Number of subdivision levels to add (1-6).

Returns Dict with object name and modifier info.

enable_dyntopo

enable_dyntopo(object_name: str, detail_size: float = 12.0, detail_mode: str = 'RELATIVE')

Enable dynamic topology (dyntopo) for adaptive sculpting resolution. Dyntopo adds and removes mesh detail dynamically as you sculpt, allowing unlimited detail where needed without uniform subdivision.

object_name	Name of the mesh object (must be in sculpt mode or will enter it).
detail_size	Detail level (smaller = more detail). Range: 0.1-500.0.
detail_mode	Detail mode. One of: RELATIVE, CONSTANT, BRUSH, MANUAL.

Returns Confirmation dict with dyntopo settings.

enter_sculpt_mode

enter_sculpt_mode(object_name: str)

Enter sculpt mode for a mesh object.

object_name	Name of the mesh object to sculpt.

Returns Confirmation dict with object name and mode.

exit_sculpt_mode

exit_sculpt_mode()

Exit sculpt mode and return to object mode.

Returns Confirmation dict with current mode.

remesh

remesh(object_name: str, voxel_size: float = 0.1, mode: str = 'VOXEL')

Remesh an object to create a clean topology.

object_name	Name of the mesh object to remesh.
voxel_size	Voxel size for remeshing (smaller = more detail). Only used in VOXEL mode.
mode	Remesh mode - VOXEL, SHARP, SMOOTH, or BLOCKS.

Returns Dict with object name and new vertex count.

set_brush_property

set_brush_property(property: str, value: Any)

Set a property on the active sculpt brush.

property	Property to set - size, strength, auto_smooth_factor, or use_frontface.
value	Value to set. size is int (1-500), strength is float (0.0-1.0), auto_smooth_factor is float (0.0-1.0), use_frontface is bool.

Returns Confirmation dict with property name and new value.

set_sculpt_brush

set_sculpt_brush(brush_type: str)

Set the active sculpt brush.

brush_type	Brush type - DRAW, CLAY, CLAY_STRIPS, INFLATE, GRAB, SMOOTH, FLATTEN, FILL, SCRAPE, PINCH, CREASE, BLOB, MASK, MULTIRES_DISPLACEMENT_SMEAR.

Returns Confirmation dict with active brush type.

set_sculpt_symmetry

set_sculpt_symmetry(use_x: bool = True, use_y: bool = False, use_z: bool = False)

Set sculpt symmetry axes. Enables symmetrical sculpting across the specified axes. X-axis symmetry is the most common for character modeling.

use_x	Enable X-axis symmetry. Defaults to True.
use_y	Enable Y-axis symmetry. Defaults to False.
use_z	Enable Z-axis symmetry. Defaults to False.

Returns Confirmation dict with symmetry settings.

Transforms 6

apply_transforms

apply_transforms(name: str, location: bool = True, rotation: bool = True, scale: bool = True)

Apply (freeze) transforms on an object, making current transforms the new basis.

name	Name of the object.
location	Apply location transform. Defaults to True.
rotation	Apply rotation transform. Defaults to True.
scale	Apply scale transform. Defaults to True.

Returns Confirmation dict.

set_location

set_location(name: str, location: list[float] | tuple[float, ...])

Set the position of an object.

name	Name of the object.
location	XYZ position as a 3-element list/tuple.

Returns Dict with the object name and new location.

set_origin

set_origin(name: str, type: str = 'GEOMETRY')

Set the origin point of an object.

name	Name of the object.
type	Origin type. One of: GEOMETRY (origin to geometry center), CURSOR (origin to 3D cursor), CENTER_OF_MASS (origin to center of mass), CENTER_OF_VOLUME (origin to center of volume). Defaults to GEOMETRY.

Returns Confirmation dict with new origin location.

set_rotation

set_rotation(name: str, rotation: list[float] | tuple[float, ...], mode: str = 'EULER')

Set the rotation of an object.

name	Name of the object.
rotation	Rotation values. For EULER mode, XYZ angles in radians (3 elements). For QUATERNION mode, WXYZ values (4 elements).
mode	Rotation mode, either EULER or QUATERNION. Defaults to EULER.

Returns Dict with the object name and new rotation.

set_scale

set_scale(name: str, scale: list[float] | tuple[float, ...])

Set the scale of an object.

name	Name of the object.
scale	XYZ scale as a 3-element list/tuple.

Returns Dict with the object name and new scale.

snap_to_grid

snap_to_grid(name: str, grid_size: float = 1.0)

Snap an object's location to the nearest grid point.

name	Name of the object.
grid_size	Size of the grid cells. Defaults to 1.0.

Returns Dict with the object name and snapped location.

UV Mapping 4

pack_uv_islands

pack_uv_islands(object_name: str, margin: float = 0.001)

Pack UV islands to fit efficiently within the UV space.

object_name	Name of the mesh object.
margin	Margin between packed islands (0.0-1.0).

Returns Confirmation dict with object name.

set_uv_projection

set_uv_projection(object_name: str, projection: str)

Apply a projection-based UV mapping to a mesh object.

object_name	Name of the mesh object.
projection	Projection type - CUBE, CYLINDER, or SPHERE.

Returns Confirmation dict with object name and projection type.

smart_uv_project

smart_uv_project(object_name: str, angle_limit: float = 66.0, island_margin: float = 0.0, area_weight: float = 0.0)

Apply Smart UV Project to a mesh object. Automatically unwraps the mesh using angle-based projection.

object_name	Name of the mesh object.
angle_limit	Angle limit in degrees for splitting faces (0.0-89.0).
island_margin	Margin between UV islands (0.0-1.0).
area_weight	Weight given to face area for island arrangement (0.0-1.0).

Returns Confirmation dict with object name and UV map info.

uv_unwrap

uv_unwrap(object_name: str, method: str = 'ANGLE_BASED')

Unwrap a mesh object's UVs using standard unwrap. Requires seams to be marked for best results.

object_name	Name of the mesh object.
method	Unwrap method - ANGLE_BASED or CONFORMAL.

Returns Confirmation dict with object name.

Viewport 3

focus_on_object

focus_on_object(object_name: str)

Frame/focus the viewport on a specific object. Selects the object and uses View Selected to center the viewport on it.

object_name	Name of the object to focus on.

Returns Confirmation dict.

set_viewport_overlay

set_viewport_overlay(overlay: str, enabled: bool)

Toggle a viewport overlay setting.

overlay	Overlay property name. One of: show_wireframes, show_face_orientation, show_floor, show_axis_x, show_axis_y, show_axis_z, show_cursor, show_object_origins, show_relationship_lines, show_stats.
enabled	Whether the overlay should be enabled.

Returns Confirmation dict with the overlay name and state.

set_viewport_shading

set_viewport_shading(mode: str)

Set the viewport shading mode.

mode	Shading mode. One of: WIREFRAME, SOLID, MATERIAL, RENDERED.

Returns Confirmation dict with the new shading mode.

Viewport Capture 1

get_viewport_screenshot

get_viewport_screenshot(max_size: int = 1000, mode: str = 'fast')

Capture a screenshot of the current Blender 3D viewport.

max_size	Maximum size in pixels for the largest dimension (default: 1000).
mode	Capture mode - 'fast' for instant viewport capture using OpenGL (default), 'full' for a complete render through the active render engine.

Returns Dict with base64-encoded PNG image data, width, height, format, and mode.