YABlenderMCP

Execute arbitrary Python code inside Blender. Pre-imported: bpy, bmesh, mathutils (Vector, Matrix, Euler, Quaternion), math, np (numpy), C (bpy.context), D (bpy.data). Stdout/stderr are captured. Assign a variable named `result` to get structured data back as JSON. Runaway code is stopped after `timeout` seconds. 3D-viewport operators work (the code runs with a viewport context). The whole run is one Ctrl+Z step. Use this for any operation that doesn't have a dedicated tool. The user can turn it off (add-on preference "Allow Python code"); then it returns an error and only the structured tools work.

Blender version, open file and unsaved state, units (mm per Blender unit), render engine, data counts, GPU and Cycles devices.

Takes no parameters.

Undo the last N steps. Every scene-changing tool call is exactly one undo step.

Redo N steps that were undone.

Run several commands in one round trip and one undo step. commands: [{"type": "<tool name>", "params": {...}}, ...] using the same names and parameters as the tools (e.g. create_object, set_transform, assign_material). Returns each command's result. Stops at the first error unless stop_on_error=False.

Set scene units. preset="mm" makes 1 Blender unit = 1 millimeter (best for 3D printing); also "cm", "m", "inch" (1 unit = 1 cm / 1 m / 1 inch). Or set system/length_unit/scale_length.

Delete every object in the scene except the given types (e.g. ["CAMERA", "LIGHT"]), then purge unused data. Undoable with the undo tool.

Read any Blender property by data path. target: an object name, "scene", "world", "view_layer", or kind:Name (material:, mesh:, light:, camera:, collection:, node_group:, image:, curve:, world:, action:). paths: e.g. ["location", "data.energy", "modifiers[\"Bevel\"].width", "render.resolution_x", "cycles.samples"]. Without paths, lists the target's properties.

Set any Blender properties by data path - lights, cameras, modifiers, render, materials... target as in get_properties. properties: {"data.energy": 800, "location[2]": 1.5, "modifiers[\"Bevel\"].segments": 4, "render.fps": 30, "cycles.samples": 64}. Errors list close property names.

Recent operators run in Blender, including what the user did by hand (useful to see what changed since your last command).

Search this Blender's Python API (operators and types) by words, e.g. "bevel", "uv unwrap". Use before guessing operator names - Blender 5.1 renamed and removed several.

Exact parameters/properties from the running Blender, e.g. "bpy.ops.mesh.primitive_cylinder_add", "Object", "Object.location", "bpy.types.SolidifyModifier", "bmesh.ops.remove_doubles".

Get an overview of the current Blender scene. Returns objects with name, type, location, visibility, dimensions (modifiers included) and vertex/face counts, plus active/selected objects, mode and units. query filters by name, types by object type (MESH, LIGHT...). Paginate with limit/offset (has_more/next_offset). Extra fields: ground (on ground / floating), bbox, rotation, scale, materials, modifiers, collections.

Get detailed information about a specific object. Returns transform (rotation also in degrees), dimensions, world bounding box, parent/children, collections, materials, modifiers, constraints, mesh stats (with modifiers evaluated), UV maps, shape keys, light or camera settings.

Create a new object in the scene and return its world bounding box. Types: cube, sphere, ico_sphere, cylinder, cone, torus, plane, circle, grid, monkey, empty, camera, light, text, bezier_curve, bezier_circle, armature. rotation is in radians. scale is baked into the mesh (object scale stays 1). params go to the primitive operator, e.g. {"radius": 0.5, "depth": 2, "vertices": 6} for a cylinder, {"size": 20} for a cube, {"body": "Hello"} for text. Note: Blender's default cube is 2 units wide and the cylinder 2 units tall.

Delete objects from the scene by name. Returns which objects were deleted and which were not found.

Select objects by name. By default deselects all other objects first. The last object in the list becomes the active object.

Set the transform (location, rotation, scale) of an object. Each parameter is an [x, y, z] list; only provided values change. Rotation is in radians unless degrees=True. relative=True adds to location/rotation and multiplies scale. Returns the new and previous values.

Duplicate an object. If linked=True, the duplicate shares the same mesh data. offset moves the copy. Returns the new object's name, type, and location.

Set a parent-child relationship between two objects (parent="" clears it). keep_transform keeps the child where it is in the world.

Get the full collection hierarchy of the scene. Returns a nested structure with collection names, their objects, and child collections.

Takes no parameters.

Move an object to a collection. Creates the collection if it doesn't exist (inside parent_collection if given). Removes the object from all current collections first.

Rename an object (and its mesh/curve data when not shared).

Hide or show objects in the viewport (hide), in renders (hide_render), or lock selection.

Join objects of the same type into the first one; the others stop existing.

Bake rotation/scale (and optionally location) into the object data. Do this before booleans, modifiers that depend on scale, and exports.

Move object origins without moving the geometry. Modes: bottom_center (centre of the bounding box floor - good for placing on a surface or print bed), geometry, center_of_mass, center_of_volume, cursor, world_origin.

Place an object against another using bounding boxes - no coordinate guessing. position: on_top, below, left, right, front, back, center, or on_ground (z=0, no target needed). gap: distance between the boxes. align: center (centre on the target's other axes; side placements share its floor) or keep.

Convert curves, text, surfaces or metaballs (and their modifiers) into meshes. Needed before mesh editing, booleans on text/curves, and print export.

Capture what the Blender 3D viewport shows and return it as an image. The max_size parameter limits the largest dimension in pixels (default 800). Smaller images keep long sessions cheap. find_object_at(x, y) identifies what is at a point of this image.

See the scene from several angles at once: returns one labeled grid image. views: front, back, left, right, top, bottom, iso, iso_back, "camera" (through the scene camera) or [x, y, z] directions (default front, right, top, iso). objects: frame only these (default all visible geometry). size: pixels per tile. shading: solid, material, wireframe (edges over the surface), wireframe_only, xray (see internal parts, e.g. print-in-place joints), clay, rendered (EEVEE only). frames: one tile per frame of the first view (check animation/motion). Orthographic unless perspective=True. The user's viewport is never changed. Use after modeling steps to verify shape, proportions and placement.

Set the viewport shading mode. Valid modes: WIREFRAME, SOLID, MATERIAL, RENDERED. Optionally toggle X-ray.

Set the 3D viewport camera angle. Valid angles: FRONT, BACK, LEFT, RIGHT, TOP, BOTTOM, ISO, CAMERA.

Frame objects in the viewport. With names, selects and frames those objects; otherwise frames the current selection (or the whole scene if nothing is selected).

List all materials in the Blender file. Returns each material's name and number of users.

Takes no parameters.

Get detailed info about a material's node tree. Returns all nodes with their type, label, location, and input default values, plus all links between nodes.

Create a new material with a Principled BSDF shader. color: [R, G, B] in 0-1. preset: plastic, matte, rubber, metal, brushed_metal, gold, copper, glass, frosted_glass, ceramic, emissive (explicit values override the preset). alpha < 1 makes it transparent.

Build a PBR material from local texture files and optionally assign it. folder: directory whose maps are recognised by filename (basecolor/albedo/diffuse, roughness, metallic, normal (GL preferred), displacement/height, ao, opacity, emission). maps: explicit {"base_color": path, "normal": path, ...}. projection: uv, box, or auto (box when the object has no UVs). scale tiles the texture.

Assign a material to an object. If slot is -1 (default), appends a new material slot. Otherwise sets the material in the specified slot index.

Set a Principled BSDF input value on a material. The property is the input name (e.g. "Base Color", "Metallic", "Roughness", "Transmission Weight", "Emission Strength"). Value is a number, or a list like [R, G, B, A] for colours.

List all modifiers on an object with their settings.

Add a modifier to an object. Type is the Blender modifier type (e.g. "SUBSURF", "BOOLEAN", "ARRAY", "MIRROR", "SOLIDIFY", "BEVEL", "REMESH", "DECIMATE", "SCREW", "WELD", "NODES"). settings is an object of property names to values, e.g. {"levels": 2}; object references take object names. Unknown settings list the valid ones; values that could freeze Blender (subdivision > 6, array > 1000...) are refused.

Set a property on a modifier (value as a number, string, bool or list).

Apply a modifier, making its effect permanent. This removes the modifier and bakes its result into the mesh.

Remove a modifier from an object without applying it.

Boolean the target with a cutter object: DIFFERENCE (cut), UNION (merge) or INTERSECT. solver: EXACT (most robust), MANIFOLD (fast, needs closed meshes - good for prints), FLOAT (fast). apply=False keeps a live modifier. cutter_action: hide, delete or keep. Returns resulting face count and dimensions; warns if the result is empty.

Import a file into Blender. Formats: .fbx, .obj, .glb, .gltf, .stl, .ply, .abc, .usd/.usda/.usdc/.usdz, .svg (as curves - extrude them for 2D-to-3D), .3mf (geometry of 3MF/Bambu Studio projects). target_size scales the import so its largest side has that size (scene units); drop_to_ground puts it on z=0; center centres it on the origin in X/Y. options: format-specific importer settings. Returns new objects and dimensions.

Export from Blender to a file (whole scene, or only the listed objects). Formats: .fbx, .obj, .glb, .gltf, .stl, .ply, .abc, .usd/.usda/.usdc/.usdz. options: format-specific exporter settings. For 3D printing use export_print (millimeters, .3mf/.stl, checks).

Save the current .blend file. If filepath is provided, saves as a new file (Save As). Otherwise saves to the current file path.

Open a .blend file, replacing the current scene. Refuses when the current file has unsaved changes unless discard_changes=True (save or save_checkpoint first). Scripts inside the file are never auto-run.

Save a timestamped copy of the scene (next to the .blend, or in the temp folder) without changing the open file. Make one before risky multi-step work; open_blend restores it.

List files in a directory. Optionally filter by file extension (e.g. ".blend", ".fbx"). Returns file names, whether each is a directory, and file sizes.

List the objects, collections, materials, node groups... inside a .blend file without opening it (and which are marked as assets).

Append (or link) data from another .blend: objects, collections, materials, node_groups, meshes, worlds, actions, images. Use with a personal library of parts (hinges, joints, pins).

The user's local asset libraries (Preferences > File Paths) and the .blend files in them.

Takes no parameters.

Add a drawing/photo/blueprint as a modeling reference. mode: empty (image empty, not rendered) or plane (textured mesh plane). view: front, back, left, right or top. size: height in scene units.

Insert a keyframe on an object property. Property is a data path like "location", "rotation_euler", "scale", or a nested one like "data.energy" (light) or "data.lens" (camera). If frame is -1, uses the current frame. value is set before keying (e.g. [1, 2, 3]). index keys one component (0=X). interpolation: CONSTANT, LINEAR, BEZIER, SINE, EXPO, BOUNCE...

Delete a keyframe from an object property. If frame is -1, deletes the keyframe at the current frame.

Set the current frame in the timeline.

Get timeline information. Returns frame start, frame end, current frame, and FPS.

Takes no parameters.

Set timeline properties. Only non-negative values are applied. Set frame_start and frame_end to define the playback range. Set fps to change the frame rate.

List an object's animated channels (data path, index, key frames, interpolation) and constraints. Works with Blender 5's slotted actions.

Change the interpolation of an object's keyframes (all, or one data path).

Remove all keyframes from an object and its data.

Add a constraint: TRACK_TO, DAMPED_TRACK, COPY_LOCATION, COPY_ROTATION, COPY_SCALE, CHILD_OF, LIMIT_LOCATION, LIMIT_ROTATION, FOLLOW_PATH, FLOOR, PIVOT, TRANSFORMATION... target: object name. settings: constraint properties (e.g. {"use_limit_x": true}).

Remove a constraint from an object.

Make a camera orbit the objects once (seamless loop) and set it active - for previews, 360° renders or checking an articulated print from every side.

Get the full node tree of a material, an object's Geometry Nodes modifier ("Object" or "Object/Modifier"), a node group, or a world ("world"). Returns nodes with bl_idname, settings (e.g. Math operation), inputs with default values or links, outputs, plus all links.

Real input/output sockets and settings of a node type in this Blender version, e.g. "ShaderNodeMix", "GeometryNodeMeshCube", "ShaderNodeMath". properties are applied first because modes change sockets (e.g. {"data_type": "RGBA"} on ShaderNodeMix).

Add a node to a node tree. Type is the node bl_idname (e.g. "ShaderNodeTexNoise", "ShaderNodeMath", "GeometryNodeMeshCube"). location: [x, y]. properties: node settings like {"operation": "MULTIPLY"}. Returns the node's input and output names.

Connect two nodes in a node tree. Sockets by name, identifier (e.g. "Value_001" for the second "Value" input of a Math node) or index ("0", "1").

Set a node input's default value (input by name, identifier or index). Value: a number, or a list for vector/color inputs (e.g. [1.0, 0.0, 0.0, 1.0]).

Set a node setting that is not a socket: Math "operation", Mix "data_type"/"blend_type", Image Texture "image" (a file path loads it), interpolation, etc.

Remove a node from a node tree.

Add a Geometry Nodes modifier with a new node group (Group Input wired to Group Output). Then build it with add_node/connect_nodes using owner "Object/Modifier".

Get current render settings. Returns engine, resolution, film transparency, output path, file format, samples, Cycles device and denoising, frame range, fps, camera, view transform.

Takes no parameters.

Set render settings. Only non-empty/non-zero values are applied. Engine: "CYCLES", "EEVEE" (BLENDER_EEVEE), "WORKBENCH". File format: "PNG", "JPEG", "OPEN_EXR", "FFMPEG" (video), etc. Samples sets the render sample count for the current engine. view_transform: "AgX", "Standard", "Filmic"... Other settings: set_properties("scene", ...).

Render Cycles on the GPU. AUTO picks OPTIX (NVIDIA RTX), then CUDA, HIP, ONEAPI, METAL; or name one, or CPU. Returns the devices found.

Render a single frame with the scene camera and show the result. If frame is -1, renders the current frame. output_path keeps the file (otherwise a temp file is used). max_size limits the preview returned to you. Long renders: raise timeout, or lower samples/resolution first.

Render an animation sequence. With Blender's UI the render runs in the background and this returns at once; poll get_render_status. wait=True blocks instead. If start/end are -1, uses the scene's frame range. output_path should include a frame placeholder (e.g. "//render_####").

Progress of the background render started by render_animation (running, frames done).

Takes no parameters.

Get mesh vertex and face data. Returns vertex positions (rounded to 5 decimals, local or world space) and face vertex indices, capped at `limit` each ("truncated" is set when cut). Set include_vertices or include_faces to False to skip those sections.

Set vertex positions by index. vertex_indices: list of integer indices, e.g. [0, 1, 2]. positions: list of [x, y, z] lists, e.g. [[1,0,0], [0,1,0], [0,0,1]].

Get all vertex groups for an object. Returns group names and indices.

Set vertex weights in a vertex group. Creates the group if it doesn't exist. vertex_indices is a list of integer indices. Weight is 0.0-1.0.

Whole-mesh edits without entering edit mode. Operations (params): merge_by_distance (distance), recalculate_normals (inside), flip_normals, triangulate, quads_from_tris (angle), subdivide (cuts, smooth), smooth_vertices (iterations, factor), shade_smooth, shade_flat, shade_auto_smooth (angle deg), decimate (ratio), remesh_voxel (voxel_size, scene units), fill_holes (sides), dissolve_degenerate (distance), delete_loose, separate_loose, separate_by_material, solidify (thickness, offset), mirror (axis "X"/"XY"...), bevel (width, segments, angle deg), uv_smart_project (angle, island_margin), convex_hull. Returns vertex/face counts before and after.

Create a light (POINT, SUN, SPOT, AREA) aimed at look_at (object name or [x,y,z]), or at the scene centre. Without energy, power is scaled to the distance so exposure is sensible at any scene scale. size: area size / sun angle (deg) / soft shadow radius.

Create a camera aimed at look_at (object name or [x,y,z]) or the scene centre, and make it the active camera. type: PERSP or ORTHO. Use frame_camera to fit objects in view.

Make a camera the scene's active (render) camera.

Aim a camera or light at an object or [x,y,z]. use_constraint=True keeps tracking it (TRACK_TO constraint).

Move/zoom the camera until the objects fill `fill` of the frame (measured from the real projection, not guessed). view optionally re-aims first: front, back, left, right, top, iso. Returns the achieved fill and whether anything is clipped.

Add a lighting setup sized to the objects: three_point, studio, rim, or outdoor (sun + sky). Lights go in the "YABlenderMCP Lights" collection.

Set the world background: a colour, or a local .hdr/.exr environment (hdri_path, rotated around Z by rotation_degrees). An HDRI world is created new; the old one is kept.

Check meshes for 3D printing (modifiers applied, sizes in mm): watertight (open/non-manifold edges), flipped or inside-out normals, self-intersections, zero-area faces, separate shells, volume, thin walls under min_wall_mm (0 skips), overhang area beyond overhang_angle from vertical, bed contact, and fit in the build volume. printer: H2C, H2D, H2S, X1C, X1E, P1S, P1P, P2S, A1, "A1 mini" - or build_volume_mm [x, y, z]. combined checks the objects as one assembly. Default objects: selection, else all visible meshes. Each issue is "blocking" or "advisory"; print_ready = no blocking issues.

Fix common print problems in place: merge duplicate vertices, remove loose and zero-area geometry, fill holes, make normals consistent and outward. voxel_remesh_mm > 0 rebuilds the mesh as a watertight solid at that resolution (loses sharp detail below it). Returns health before/after.

Get objects ready to slice: orientation keep, flat (largest flat face down) or min_overhang (least support area, from convex-hull resting faces); drop to z=0; centre on the origin. as_group keeps an assembly rigid (print-in-place parts). Returns overhang/contact area and dimensions in mm.

Check gaps between parts for print-in-place joints and assemblies: reports pairs that intersect (would fuse), touch, or are closer than min_clearance_mm, with the measured clearance. split_shells=True compares the separate shells inside each object.

Export for the slicer in millimeters with modifiers applied. .3mf: one file, each object a separate part with its material colour (opens in Bambu Studio, Orca, Prusa). .stl: merged, or one per object (separate_files). check=True reports blocking print issues per object.

Model a solid from signed-distance shapes (millimeters) - always closed and manifold, with exact clearances and smooth fillets. Ideal for pins, sockets, ball joints, hinges. shapes (applied in order): {"type": ..., "op": "union"|"subtract"|"intersect", "smooth": fillet_mm, ...}. sphere: center, radius. box: center, size [x,y,z], rounding, rotation [deg]. cylinder: center + height + radius (Z axis) or start/end + radius. capsule: start, end, radius. cone: start, end, radius_start, radius_end. torus: center, major_radius, minor_radius, rotation. mesh: object (existing closed mesh), offset (mm; +grows) - e.g. subtract a pin's mesh with offset 0.3 to cut a socket with 0.3 mm clearance. Smaller voxel_size_mm = finer detail, more memory.

Distance between two objects: origins, bounding boxes and closest surfaces (gap, 0 when they touch or intersect), with the closest points.

Cast a ray into the scene: first object hit, hit location, surface normal and distance.

Which object is at a point of the last get_viewport_screenshot? x, y from 0 to 1, measured from the image's top-left corner.

Remember the scene state (transforms, mesh data, materials, lights, cameras) so diff_scene can prove what an edit changed - and that nothing else did.

What changed since snapshot_scene(name): added, removed, and changed items with the fields that differ.

Compare the model's outline with a 2D reference (drawing/photo with transparency, or a dark shape on a light background) - the check for 2D-to-3D work. Renders the objects' silhouette from an orthographic view (front, back, left, right, top, bottom), fits both outlines to the same box (position and scale ignored), and returns IoU (1.0 = identical) plus an overlay: gray = both, blue = model only, red = reference only.

How to work well with these Blender tools: what is available, which tool to use for what, how to check results, units, undo, the 3D-print and 2D-to-3D workflows, Blender 5.1 API pitfalls and what errors mean. Read it once before multi-step work.

Takes no parameters.