Get detailed information about the current Blender scene

Get detailed information about a specific object in the Blender scene.

Parameters:

• object_name: The name of the object to get information about

Capture a screenshot of the current Blender 3D viewport.

Parameters:

• max_size: Maximum size in pixels for the largest dimension (default: 800)

Returns the screenshot as an Image.

Execute arbitrary Python code in Blender. Make sure to do it step-by-step by breaking it into smaller chunks.

Parameters:

• code: The Python code to execute

Get a list of categories for a specific asset type on Polyhaven.

Parameters:

• asset_type: The type of asset to get categories for (hdris, textures, models, all)

Search for assets on Polyhaven with optional filtering.

Parameters:

• asset_type: Type of assets to search for (hdris, textures, models, all)

• categories: Optional comma-separated list of categories to filter by

Returns a list of matching assets with basic information.

Download and import a Polyhaven asset into Blender.

Parameters:

• asset_id: The ID of the asset to download

• asset_type: The type of asset (hdris, textures, models)

• resolution: The resolution to download (e.g., 1k, 2k, 4k)

• file_format: Optional file format (e.g., hdr, exr for HDRIs; jpg, png for textures; gltf, fbx for models)

Returns a message indicating success or failure.

Apply a previously downloaded Polyhaven texture to an object.

Parameters:

• object_name: Name of the object to apply the texture to

• texture_id: ID of the Polyhaven texture to apply (must be downloaded first)

Returns a message indicating success or failure.

Check if PolyHaven integration is enabled in Blender. Returns a message indicating whether PolyHaven features are available.

Check if Hyper3D Rodin integration is enabled in Blender. Returns a message indicating whether Hyper3D Rodin features are available.

Don't emphasize the key type in the returned message, but sliently remember it.

Check if Sketchfab integration is enabled in Blender. Returns a message indicating whether Sketchfab features are available.

Search for models on Sketchfab with optional filtering.

Parameters:

• query: Text to search for

• categories: Optional comma-separated list of categories

• count: Maximum number of results to return (default 20)

• downloadable: Whether to include only downloadable models (default True)

Returns a formatted list of matching models.

Get a preview thumbnail of a Sketchfab model by its UID. Use this to visually confirm a model before downloading.

Parameters:

• uid: The unique identifier of the Sketchfab model (obtained from search_sketchfab_models)

Returns the model's thumbnail as an Image for visual confirmation.

Download and import a Sketchfab model by its UID. The model will be scaled so its largest dimension equals target_size.

Parameters:

• uid: The unique identifier of the Sketchfab model

• target_size: REQUIRED. The target size in Blender units/meters for the largest dimension. You must specify the desired size for the model. Examples: - Chair: target_size=1.0 (1 meter tall) - Table: target_size=0.75 (75cm tall) - Car: target_size=4.5 (4.5 meters long) - Person: target_size=1.7 (1.7 meters tall) - Small object (cup, phone): target_size=0.1 to 0.3

Returns a message with import details including object names, dimensions, and bounding box. The model must be downloadable and you must have proper access rights.

Generate 3D asset using Hyper3D by giving description of the desired asset, and import the asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful.

Parameters:

• text_prompt: A short description of the desired model in English.

• bbox_condition: Optional. If given, it has to be a list of floats of length 3. Controls the ratio between [Length, Width, Height] of the model.

Returns a message indicating success or failure.

Generate 3D asset using Hyper3D by giving images of the wanted asset, and import the generated asset into Blender. The 3D asset has built-in materials. The generated model has a normalized size, so re-scaling after generation can be useful.

Parameters:

• input_image_paths: The absolute paths of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in MAIN_SITE mode.

• input_image_urls: The URLs of input images. Even if only one image is provided, wrap it into a list. Required if Hyper3D Rodin in FAL_AI mode.

• bbox_condition: Optional. If given, it has to be a list of ints of length 3. Controls the ratio between [Length, Width, Height] of the model.

Only one of {input_image_paths, input_image_urls} should be given at a time, depending on the Hyper3D Rodin's current mode. Returns a message indicating success or failure.

Check if the Hyper3D Rodin generation task is completed.

For Hyper3D Rodin mode MAIN_SITE: Parameters: - subscription_key: The subscription_key given in the generate model step.

Returns a list of status. The task is done if all status are "Done".
If "Failed" showed up, the generating process failed.
This is a polling API, so only proceed if the status are finally determined ("Done" or "Canceled").

For Hyper3D Rodin mode FAL_AI: Parameters: - request_id: The request_id given in the generate model step.

Returns the generation task status. The task is done if status is "COMPLETED".
The task is in progress if status is "IN_PROGRESS".
If status other than "COMPLETED", "IN_PROGRESS", "IN_QUEUE" showed up, the generating process might be failed.
This is a polling API, so only proceed if the status are finally determined ("COMPLETED" or some failed state).

Import the asset generated by Hyper3D Rodin after the generation task is completed.

Parameters:

• name: The name of the object in scene

• task_uuid: For Hyper3D Rodin mode MAIN_SITE: The task_uuid given in the generate model step.

• request_id: For Hyper3D Rodin mode FAL_AI: The request_id given in the generate model step.

Only give one of {task_uuid, request_id} based on the Hyper3D Rodin Mode! Return if the asset has been imported successfully.

Check if Hunyuan3D integration is enabled in Blender. Returns a message indicating whether Hunyuan3D features are available.

Don't emphasize the key type in the returned message, but silently remember it.

Generate 3D asset using Hunyuan3D by providing either text description, image reference, or both for the desired asset, and import the asset into Blender. The 3D asset has built-in materials.

Parameters:

• text_prompt: (Optional) A short description of the desired model in English/Chinese.

• input_image_url: (Optional) The local or remote url of the input image. Accepts None if only using text prompt.

Returns:

• When successful, returns a JSON with job_id (format: "job_xxx") indicating the task is in progress

• When the job completes, the status will change to "DONE" indicating the model has been imported

• Returns error message if the operation fails

Check if the Hunyuan3D generation task is completed.

For Hunyuan3D: Parameters: - job_id: The job_id given in the generate model step.

Returns the generation task status. The task is done if status is "DONE".
The task is in progress if status is "RUN".
If status is "DONE", returns ResultFile3Ds, which is the generated ZIP model path
When the status is "DONE", the response includes a field named ResultFile3Ds that contains the generated ZIP file path of the 3D model in OBJ format.
This is a polling API, so only proceed if the status are finally determined ("DONE" or some failed state).

Import the asset generated by Hunyuan3D after the generation task is completed.

Parameters:

• name: The name of the object in scene

• zip_file_url: The zip_file_url given in the generate model step.

Return if the asset has been imported successfully.

Launch Blender as a managed subprocess.

Parameters:

• blend_file: Path to a .blend file to open on startup (optional)

• blender_exe: Full path to the Blender executable. Auto-detected if omitted (checks BLENDER_EXE env var, PATH, then common install locations).

• background: True = headless mode (--background), no UI. Useful for rendering.

• wait_for_addon: Wait up to 30 s for the BlenderMCP addon socket to become reachable on port 9876 (default True). Set False for background jobs that don't use the addon.

• python_expr: Optional Python expression passed to Blender via --python-expr, e.g. "import bpy; bpy.ops.wm.quit_blender()" for scripted batch runs.

Close the Blender instance that was started with start_blender().

Parameters:

• force: If True, kills the process immediately instead of asking Blender to quit gracefully via its Python API (default False).

Report whether Blender is running, and whether the MCP addon is reachable.

Capture the Blender 3D viewport from a named angle and return it as an image.

Parameters:

• angle: View direction. One of: front, back, left, right, top, bottom, iso_front_right, iso_front_left

• max_size: Maximum pixel dimension (default 800)

Capture multiple viewport angles and stitch them into a single contact sheet image.

Parameters:

• angles: Comma-separated list of angle names (default: front,right,top,iso_front_right)

• max_size: Pixel size for each individual tile (default 512)

Returns a single composited image with all requested angles labelled.

Render a normalised depth map from the active camera using the Blender compositor Z-pass. Closer objects appear lighter.

Parameters:

• max_depth: Depth value (scene units) mapped to black (default 10.0)

Store a local image file as a named reference for later comparison tools.

Parameters:

• name: Short identifier (e.g. "concept_art")

• filepath: Absolute path to the image file on disk

Capture the current viewport from a named angle and composite it side-by-side with a previously stored reference image.

Parameters:

• reference_name: Name given to store_reference_image earlier

• angle: Viewport angle to capture for comparison

• max_size: Tile size for each image in the composite

Compare two images and produce a 3-panel composite: [Image A] | [Image B] | [Diff]. The diff panel desaturates the base image and paints changed regions in bright red, making differences immediately obvious.

Parameters:

• image_path_a: Path to the first image (treated as the reference/baseline)

• image_path_b: Path to the second image (treated as the new/changed version)

• threshold: Pixel difference (0-255) below which changes are ignored (default 15, filters noise)

• tile_size: Width/height of each panel in the composite (default 512)

Move an object to an absolute world-space position.

Set the absolute scale of an object on each axis.

Set the Euler rotation of an object (degrees).

Parameters:

• name: Object name

• x, y, z: Rotation in degrees around each axis

Set the Principled BSDF base colour of an object's material. Creates the material if one does not exist.

Parameters:

• name: Object name

• r, g, b, a: Colour channels in 0..1 range

• material_index: Which material slot to update (default 0)

Read vertex positions from a mesh object.

Parameters:

• name: Mesh object name

• indices: Comma-separated vertex indices to retrieve (returns all if omitted)

• world_space: True = world coordinates (default), False = local/object coordinates

• max_verts: Safety cap when retrieving all vertices (default 2000)

Returns JSON with each vertex's index and [x, y, z] position.

Move a single vertex of a mesh object to a world-space position.

Parameters:

• name: Mesh object name

• vertex_index: Zero-based vertex index

• x, y, z: Target world-space position

Batch-update multiple vertex positions in a single call (much faster than calling set_vertex_position repeatedly for many vertices).

Parameters:

• name: Mesh object name

• vertices: JSON array of {"index": int, "co": [x, y, z]} objects. Example: '[{"index":0,"co":[0,0,1]},{"index":3,"co":[1,0,0]}]'

• world_space: True = co values are world-space (default), False = local/object space

Read the control points of a curve (BEZIER, POLY, or NURBS) object.

For BEZIER curves returns: co, handle_left, handle_right, handle types. For POLY/NURBS curves returns: co (and weight for NURBS).

Parameters:

• name: Curve object name

• spline_index: Which spline within the curve (default 0)

Move a curve control point and optionally adjust its bezier handles.

Parameters:

• name: Curve object name

• point_index: Zero-based control point index

• co: Comma-separated x,y,z world-space position

• handle_left: Comma-separated x,y,z for left handle (bezier only)

• handle_right: Comma-separated x,y,z for right handle (bezier only)

• handle_left_type: FREE, ALIGNED, VECTOR, or AUTO (bezier only)

• handle_right_type: FREE, ALIGNED, VECTOR, or AUTO (bezier only)

• spline_index: Spline index within the curve object (default 0)

Read edge data from a mesh: vertex pair, sharp flag, seam flag, crease, and bevel weight.

Parameters:

• name: Mesh object name

• indices: Comma-separated edge indices (returns all if omitted)

• max_edges: Safety cap when retrieving all edges (default 5000)

Mark edges as sharp (hard) or soft, controlling auto-smooth and the Edge Split modifier.

Sharp edges appear as hard creases when smooth shading + auto-smooth is enabled. Soft (unsharp) edges blend smoothly with neighbouring faces.

Parameters:

• name: Mesh object name

• edge_indices: Comma-separated edge indices, or "all"

• sharp: True = hard edge (default), False = soft/smooth edge

Set subdivision crease weight on edges.

Crease controls how the Subdivision Surface modifier handles edge sharpness: 0.0 = fully smooth (no crease), 1.0 = perfectly sharp crease. Values in between give progressively harder edges without going fully sharp.

Parameters:

• name: Mesh object name

• edge_indices: Comma-separated edge indices, or "all"

• crease: Weight 0.0–1.0

Set bevel weight on edges, used with the Bevel modifier (limit_method=WEIGHT).

Only edges with weight > 0 will be bevelled when the modifier uses WEIGHT mode. This lets you selectively bevel specific edges without affecting the whole mesh.

Typical workflow:

1. set_edge_bevel_weight("Cube", "4,5,6,7", weight=1.0) ← top edges only

2. add_modifier("Cube", "BEVEL", params='{"width": 0.05, "limit_method": "WEIGHT"}')

Parameters:

• name: Mesh object name

• edge_indices: Comma-separated edge indices, or "all"

• weight: 0.0 (no bevel) to 1.0 (full bevel)

Read face data from a mesh object.

Parameters:

• name: Mesh object name

• indices: Comma-separated face indices to retrieve (returns all if omitted)

• world_space: True = world coordinates for normals and centers (default)

• max_faces: Safety cap when retrieving all faces (default 2000)

Returns JSON with each face's vertex_indices, normal, center, material_index, and area.

Assign a material slot to specific faces (for multi-material objects).

Parameters:

• name: Mesh object name

• face_indices: Comma-separated face indices, or "all" for every face

• material_index: Material slot number (0-based; material must already be in the object's slots)

Extrude faces outward along their individual normals.

Parameters:

• name: Mesh object name

• face_indices: Comma-separated face indices to extrude

• amount: Extrusion distance in Blender units (negative = inward, default 0.2)

Inset faces, creating a border ring of new polygons inside each face.

Parameters:

• name: Mesh object name

• face_indices: Comma-separated face indices to inset

• thickness: Inset distance from face edges (default 0.1)

• depth: Push inset faces along their normals — 0 = flat, positive = raised

• use_individual: Inset each face independently (default True)

Flip face normals on a mesh (reverses which side is the outside).

Parameters:

• name: Mesh object name

• face_indices: Comma-separated face indices (flips ALL faces if omitted)

Merge (weld) vertices that are within a distance threshold of each other. Equivalent to 'Merge by Distance' in Blender — useful for cleaning up imported meshes or fixing seams after boolean operations.

Parameters:

• name: Mesh object name

• distance: Maximum distance between vertices to merge (default 0.001)

Triangulate all faces of a mesh (convert quads/ngons to triangles). Useful before export to game engines or 3D printing.

Parameters:

• name: Mesh object name

• method: BEAUTY (best quality, default), FIXED, FIXED_ALTERNATE, SHORTEST_DIAGONAL

Subdivide all faces of a mesh (equivalent to Subdivide in Edit Mode).

Parameters:

• name: Mesh object name

• cuts: Number of cuts per edge (default 1)

• smoothness: Smooth factor 0..1 (default 0.0 = flat)

Apply a named modifier on a mesh object, collapsing it into the mesh data.

Parameters:

• name: Object name

• modifier_name: Exact modifier name as shown in Blender's Properties panel

Return detailed topology statistics for a mesh object.

Parameters:

• name: Mesh object name

Add a new camera to the Blender scene.

Parameters:

• name: Name for the camera object

• location: Comma-separated x,y,z position (default "0,-5,3")

• look_at: Comma-separated x,y,z target point (default "0,0,0")

• lens: Focal length in mm (default 50.0)

• cam_type: PERSP or ORTHO (default PERSP)

Set the active render camera to an existing camera object.

Parameters:

• name: Camera object name

Render a still from the specified (or active) camera.

Parameters:

• camera_name: Camera to render from (uses scene active camera if omitted)

• width: Render width in pixels (default 1920)

• height: Render height in pixels (default 1080)

• samples: Cycles sample count, ignored for EEVEE (default 32)

Render a still from every camera in the scene simultaneously and return a contact sheet with all results labelled by camera name.

Parameters:

• width: Render width per camera in pixels (default 1920)

• height: Render height per camera in pixels (default 1080)

• samples: Cycles sample count (default 32, ignored for EEVEE)

• output_dir: Directory to save individual renders (temp dir if omitted)

Returns a composited contact sheet image. Individual renders are also saved to output_dir so you can access them at full resolution.

List all objects in the scene that match the given type.

Parameters:

• obj_type: Blender object type: MESH, CURVE, CAMERA, LIGHT, EMPTY, ARMATURE, etc.

Measure the Euclidean distance between the origins of two objects.

Parameters:

• name_a: First object name

• name_b: Second object name

Add a light to the Blender scene.

Parameters:

• light_type: POINT, SUN, SPOT, or AREA

• name: Name for the light object (optional)

• location: Comma-separated x,y,z (default "0,0,5")

• energy: Light power in watts (default 1000)

• color: Comma-separated r,g,b in 0..1 range (default "1,1,1")

• radius: Shadow soft radius (default 0.1)

Set the scene world background to a solid colour or an HDRI environment map.

Parameters:

• color: Comma-separated r,g,b in 0..1 range (used when hdri_path is not given)

• strength: Background emission strength (default 1.0)

• hdri_path: Absolute path to a .hdr or .exr file (overrides color)

Add a classic 3-point lighting rig (key, fill, back/rim) centred on a subject.

Parameters:

• subject_name: Object to light (uses scene origin if omitted)

• key_energy: Key light power in watts (default 1500)

• fill_energy: Fill light power in watts (default 500)

• back_energy: Back/rim light power in watts (default 800)

Export an object (or the full scene) to a 3D file.

Parameters:

• name: Object to export; exports entire scene if omitted

• filepath: Output file path (auto-generated in temp dir if omitted)

• file_format: glb, gltf, fbx, obj, stl, ply (default glb)

Import a 3D file into the current Blender scene. Supports: .glb, .gltf, .fbx, .obj, .stl, .ply, .blend

Parameters:

• filepath: Absolute path to the file to import

Save the current Blender project as a .blend file.

Parameters:

• filepath: Absolute path to save to (e.g. "C:/projects/my_scene.blend"). If omitted, saves over the currently open file. If the file has never been saved, a temporary path is used and returned.

Open a .blend file, replacing the current Blender scene. Unsaved changes to the current file will be lost — save first if needed.

Parameters:

• filepath: Absolute path to the .blend file to open

Add a standard mesh primitive to the Blender scene.

Parameters:

• primitive_type: cube, plane, circle, sphere, ico_sphere, cylinder, cone, torus, monkey

• location: Comma-separated x,y,z (default "0,0,0")

• size: Overall size in Blender units (default 2.0)

• name: Optional name for the new object

• rotation: Comma-separated x,y,z rotation in degrees (default "0,0,0")

Delete an object from the scene and purge orphaned mesh/material data.

Parameters:

• name: Object name to delete

Duplicate an object.

Parameters:

• name: Source object name

• new_name: Name for the duplicate (auto-assigned if omitted)

• offset: Comma-separated x,y,z displacement from original (default "0.5,0.5,0")

• linked: If True, shares mesh data with original (instance); False = full copy

Join multiple mesh objects into one.

Parameters:

• names: Comma-separated list of object names to join

• result_name: Name for the joined object (defaults to the first object's name)

Separate a mesh object into multiple objects.

Parameters:

• name: Mesh object name

• method: LOOSE (by disconnected geometry), MATERIAL (by material slot), SELECTED (by face selection)

Rename an object and its mesh data block.

Parameters:

• old_name: Current object name

• new_name: Desired new name

Set an object's origin point.

Parameters:

• name: Object name

• origin_type: ORIGIN_GEOMETRY (centre of mesh), ORIGIN_CURSOR (3D cursor position), ORIGIN_CENTER_OF_MASS, ORIGIN_CENTER_OF_VOLUME

Move an object so its lowest bounding-box point rests on the ground plane.

Parameters:

• name: Object name

• ground_z: Z value of the ground plane (default 0.0)

Toggle smooth or flat shading on a mesh object.

Parameters:

• name: Mesh object name

• smooth: True for smooth shading, False for flat

• auto_smooth: Enable auto-smooth (smooths only edges below angle threshold)

• angle: Auto-smooth threshold in degrees (default 30°)

Parent one object to another, creating a hierarchy.

Parameters:

• child_name: Object that becomes the child

• parent_name: Object that becomes the parent

• keep_transform: Preserve the child's world-space position (default True)

Select or deselect objects by name list and/or type.

Parameters:

• names: Comma-separated object names (if omitted, applies to all or filtered by type)

• action: SELECT, DESELECT, TOGGLE

• obj_type: Filter by type when names is omitted: MESH, CAMERA, LIGHT, CURVE, etc.

Align multiple objects' origins along one axis.

Parameters:

• names: Comma-separated object names

• axis: X, Y, or Z

• align_to: FIRST, LAST, MIN, MAX, AVERAGE

Create (or replace) a PBR material using Principled BSDF.

Parameters:

• name: Material name

• base_color: Comma-separated r,g,b in 0..1 (default "0.8,0.8,0.8")

• metallic: 0.0 (dielectric) to 1.0 (fully metallic)

• roughness: 0.0 (mirror) to 1.0 (fully rough)

• emission_color: Comma-separated r,g,b to enable glow (e.g. "1,0.5,0")

• emission_strength: Emission multiplier (default 1.0)

• alpha: Opacity 0..1 (values < 1 enable alpha blending)

• assign_to: Object name to auto-assign this material to (slot 0)

Assign an existing material to an object's material slot.

Parameters:

• object_name: Target object

• material_name: Material to assign (must already exist)

• slot: Material slot index (default 0)

Load an image file and wire it into a material's texture slot.

Parameters:

• material_name: Target material (must have a Principled BSDF node)

• image_path: Absolute path to the image file

• texture_slot: 'Base Color', 'Roughness', 'Metallic', 'Normal', 'Emission Color'

• uv_scale: Uniform UV tiling scale (default 1.0)

Add a modifier to an object with optional parameters.

Parameters:

• name: Object name

• modifier_type: MIRROR, BEVEL, ARRAY, SOLIDIFY, SUBSURF, DECIMATE, DISPLACE, SHRINKWRAP, WIREFRAME, SKIN, LATTICE, CAST, etc.

• modifier_name: Display name for the modifier (auto-generated if omitted)

• params: JSON string of modifier properties, e.g.: MIRROR: '{"use_axis": [true, false, false], "use_clip": true}' BEVEL: '{"width": 0.1, "segments": 3}' ARRAY: '{"count": 4, "relative_offset_displace": [1, 0, 0]}' SOLIDIFY: '{"thickness": 0.05}' SUBSURF: '{"levels": 2, "render_levels": 3}'

Returns the modifier name so you can reference it later with apply_modifier.

Perform a boolean operation between two mesh objects.

Parameters:

• target_name: Object to modify (the base mesh)

• cutter_name: Object used as the cutting/joining tool

• operation: DIFFERENCE (subtract), UNION (merge), INTERSECT (keep overlap)

• solver: EXACT (better quality) or FAST (faster but less reliable)

• apply: If True (default), applies the modifier and deletes the cutter object

Configure scene render settings.

Parameters:

• engine: CYCLES (ray-traced, photorealistic), BLENDER_EEVEE (real-time), BLENDER_WORKBENCH (solid view)

• width / height: Render resolution in pixels

• samples: Number of render samples (affects quality/noise)

• output_path: File path for saved renders (e.g. "C:/renders/frame_####.png")

• file_format: PNG, JPEG, EXR, TIFF

• transparent_background: True to render with alpha instead of background colour

Insert an animation keyframe on an object property.

Parameters:

• name: Object name

• data_path: Property to key — 'location', 'rotation_euler', 'scale', or any animatable path like 'data.energy'

• frame: Frame number (uses current frame if omitted)

• value: Comma-separated values to set before keying, e.g. "1,2,3" for location. Rotation values are in degrees and converted automatically.

Set the current scene frame (scrubs the timeline).

Parameters:

• frame: Target frame number

Create a new collection for scene organisation.

Parameters:

• name: Collection name

• parent_collection: Optional parent collection name (nests inside it)

Move objects into a collection (removes them from all other collections).

Parameters:

• object_names: Comma-separated object names

• collection_name: Target collection (must already exist)

Start the local image-to-3D inference server (TripoSR). The server process is kept running until unload_img_to_3d_model() is called. Frees VRAM when unloaded — load only when you need it.

Parameters:

• model_dir: Path to TripoSR weights directory (uses IMG_TO_3D_MODEL_DIR env var if omitted)

Stop the local image-to-3D server, freeing VRAM and memory.

Generate a 3D mesh (.glb) from a single image using the local TripoSR model. You must call load_img_to_3d_model() first.

Parameters:

• image_path: Absolute path to the input image

• output_path: Where to save the .glb file (auto-generated if omitted)

• foreground_ratio: Foreground crop ratio for background removal (default 0.85)

• mc_resolution: Marching-cubes resolution; higher = more detail but slower (default 256)

• no_remove_bg: Skip background removal if the image already has a clean background