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.

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

Args: 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.

List all scenes in the current Blender file.

Returns a list of dicts, each containing the scene name and object count.

Create a new scene.

Args: name: Name for the new scene.

Returns: Confirmation dict with the created scene name.

Delete a scene by name.

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

Returns: Confirmation dict.

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.

Args: 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.

Create a primitive object in the scene.

Args: 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 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.

Args: 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 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.

Args: 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 an object from the scene by name.

Args: name: Name of the object to delete.

Returns: Confirmation dict.

Duplicate an object.

Args: 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.

Rename an object.

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

Returns: Dict with old and new names.

Select objects by name.

Args: 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.

Get detailed information about an object.

Args: name: Name of the object.

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

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

Args: 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.

Set object visibility in viewport and/or render.

Args: 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.

Set parent-child relationship between two objects.

Args: child: Name of the child object. parent: Name of the parent object.

Returns: Confirmation dict.

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.

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

Returns: Dict with the resulting joined object name.

Set the origin point of an object.

Args: object_name: Name of the object. type: Origin type. One of: ORIGIN_GEOMETRY, ORIGIN_CURSOR, ORIGIN_CENTER_OF_MASS, ORIGIN_CENTER_OF_VOLUME, GEOMETRY_ORIGIN.

Returns: Confirmation dict.

Convert an object to a different type.

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

Returns: Confirmation dict.

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.

Args: 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.

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

Args: 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.

Set the position of an object.

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

Returns: Dict with the object name and new location.

Set the rotation of an object.

Args: 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 the scale of an object.

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

Returns: Dict with the object name and new scale.

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

Args: 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.

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

Args: 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.

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.

Args: 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.

Remove a modifier from an object.

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

Returns: Confirmation dict.

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

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

Returns: Confirmation dict.

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

Args: 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.

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.

Args: 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.

Subdivide a mesh.

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

Returns: Confirmation dict.

Extrude all faces of a mesh along their normals.

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

Returns: Confirmation dict.

Bevel all edges of a mesh.

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

Returns: Confirmation dict.

Add loop cuts to a mesh object.

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

Returns: Confirmation dict.

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.

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

Returns: Confirmation dict.

Merge vertices by distance.

Args: 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.

Separate a mesh into parts.

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

Returns: Confirmation dict.

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.

Args: 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.

Create a new material with a Principled BSDF shader node.

Args: name: Name for the new material.

Returns: Confirmation dict with the created material name.

Assign a material to an object.

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

Returns: Confirmation dict.

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

Args: 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 a property on a material's Principled BSDF node.

Args: 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.

Create a fully configured Principled BSDF material in one call.

Args: 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.

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

Args: 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.

Set the blend mode of a material (EEVEE).

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

Returns: Confirmation dict.

List all materials in the current Blender file.

Returns: List of dicts with material name and user count.

Delete a material by name.

Args: material_name: Name of the material to delete.

Returns: Confirmation dict.

Duplicate a material with a new name.

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

Returns: Confirmation dict with the new material name.

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

Args: 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.

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

Args: 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.

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

Args: 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.

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

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

Returns: Confirmation dict.

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

Args: material_name: Name of the material.

Returns: Dict with nodes list and links list.

Create a new light in the scene.

Args: 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.

Set a property on a light object.

Args: 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 the world background to a solid color or HDRI environment map.

Args: 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.

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

Args: 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.

List all light objects in the scene.

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

Delete a light object from the scene.

Args: name: Name of the light object to delete.

Returns: Confirmation dict.

Configure shadow settings for a light.

Args: 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.

Create a new camera in the scene.

Args: 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.

Set a property on a camera.

Args: 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.

Set the active scene camera.

Args: name: Name of the camera object to make active.

Returns: Confirmation dict.

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

Args: 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.

Render the viewport to a file or return as base64.

Args: 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.

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

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

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

Args: 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.

Remove a keyframe from an object property at a specific frame.

Args: object_name: Name of the object. data_path: Property data path (e.g., location, rotation_euler, scale). frame: Frame number of the keyframe to remove.

Returns: Confirmation dict.

Set the current frame in the timeline.

Args: frame: Frame number to set as current.

Returns: Confirmation dict with the new current frame.

Set the start and end frames of the scene timeline.

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

Returns: Confirmation dict with the new frame range.

Set the interpolation type for keyframes on a property.

Args: object_name: Name of the object. data_path: Property data path. interpolation: Interpolation type. One of: CONSTANT, LINEAR, BEZIER, SINE, QUAD, CUBIC, QUART, QUINT, EXPO, CIRC, BACK, BOUNCE, ELASTIC.

Returns: Confirmation dict.

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

Args: 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.

List all keyframes on an object.

Args: object_name: Name of the object.

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

Remove all animation data from an object.

Args: object_name: Name of the object.

Returns: Confirmation dict.

Set the render engine.

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

Returns: Confirmation dict with the active render engine.

Set the render resolution.

Args: 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 the number of render samples.

Args: samples: Number of samples. Range: 1-10000.

Returns: Confirmation dict with the new sample count.

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

Args: 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.

Render the current scene to an image file.

Args: 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.

Render the animation sequence to image files.

Args: 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.

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.

Args: 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.

Create a new curve object.

Args: 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.

Add a control point to an existing curve.

Args: 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.

Set a property on a curve object.

Args: 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.

Convert a curve object to a mesh object.

Args: curve_name: Name of the curve object to convert.

Returns: Dict with the converted object name.

Create a 3D text object.

Args: 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.

Switch the direction of a curve's splines.

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of direction switch.

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

Args: 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.

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

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of cyclic toggle.

Subdivide a curve by adding control points between existing ones.

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

Returns: Dict with confirmation of subdivision.

Smooth the control points of a curve.

Args: curve_name: Name of the curve object.

Returns: Dict with confirmation of smoothing.

Enter sculpt mode for a mesh object.

Args: object_name: Name of the mesh object to sculpt.

Returns: Confirmation dict with object name and mode.

Exit sculpt mode and return to object mode.

Returns: Confirmation dict with current mode.

Set the active sculpt brush.

Args: 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 a property on the active sculpt brush.

Args: 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.

Remesh an object to create a clean topology.

Args: 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.

Add a Multiresolution modifier for sculpting detail.

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

Returns: Dict with object name and modifier info.

Set sculpt symmetry axes.

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

Args: 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.