Check whether Blender is running and the bridge addon is reachable.

Use this as the first step before any other tool to confirm the integration is live.

Returns: JSON with status and a message indicating reachability.

Example: blender_ping() → {"status": "success", "result": {"reachable": true}}

Get an overview of the current Blender scene.

Returns scene name, frame range, render engine, and total object count.

Args: params: GetSceneInfoInput with response_format ('markdown' or 'json').

Returns: Markdown summary or JSON object describing the scene.

Example: blender_get_scene_info(response_format="json")

List objects in the current Blender scene, optionally filtered by type.

Args: params: ListObjectsInput with optional object_type filter (e.g. 'MESH') and response_format.

Returns: Markdown table or JSON list of objects with name, type, and location.

Example: blender_list_objects(object_type="MESH", response_format="json")

Get detailed information about a specific object by name.

Returns transform, dimensions, material slots, and type-specific data (mesh stats for MESH, light settings for LIGHT, focal length for CAMERA).

Args: params: GetObjectInfoInput with the object name and response_format.

Returns: Markdown summary or JSON with full object properties.

Example: blender_get_object_info(name="Cube")

Save the current Blender scene to a .blend file.

Args: params: SaveFileInput with optional filepath. Uses the currently open file path if omitted.

Returns: JSON with the path the file was saved to.

Example: blender_save_file(filepath="/tmp/my_scene.blend") blender_save_file() # saves to current file path

Open a .blend file in Blender, replacing the current scene.

WARNING: Unsaved changes to the current scene will be lost.

Args: params: OpenFileInput with filepath (absolute path to .blend file).

Returns: JSON confirming the file that was opened.

Example: blender_open_file(filepath="/home/user/projects/scene.blend")

Capture a screenshot of the current Blender 3D viewport.

Renders using OpenGL and returns the image inline. Great for inspecting the current state of the scene visually.

Args: params: ViewportScreenshotInput with max_size (default 800px).

Returns: An inline PNG image of the viewport, or an error string if capture fails.

Example: blender_get_viewport_screenshot(max_size=1024)

Create a primitive mesh (cube, sphere, cylinder, etc.) in the scene.

Args: params: CreatePrimitiveInput with primitive_type, optional name, location (x, y, z), and size.

Returns: JSON describing the newly created object.

Example: blender_create_primitive(primitive_type="cube", name="MyCube", location=(0,0,1))

Set location, rotation, and/or scale of an existing object.

Any field left as None is left unchanged. This is idempotent — calling with the same values is a no-op.

Args: params: TransformObjectInput with the target object name and any combination of location, rotation_euler, and scale.

Returns: JSON with the updated transform values.

Example: blender_transform_object(name="Cube", location=(1,0,0), scale=(2,2,2))

Delete an object from the scene by name.

DESTRUCTIVE: permanently removes the object. Idempotent: deleting a missing object returns success with a note.

Args: params: DeleteObjectInput with the exact name of the object to delete.

Returns: JSON confirming the deletion.

Example: blender_delete_object(name="Cube")

Apply a PBR material to an object using Principled BSDF.

Creates or updates a material with the given base color, metallic, roughness, and optional emission. Assigns it to the first material slot of the object.

Args: params: SetMaterialInput with object_name, color (RGBA), metallic, roughness, optional material_name, and optional emission.

Returns: JSON with the material name and applied properties.

Example: blender_set_material(object_name="Cube", color=(0.2, 0.4, 0.8, 1.0), metallic=0.9)

Add a light source to the scene.

Supports POINT (omnidirectional), SUN (directional), SPOT (cone), and AREA (panel) lights.

Args: params: AddLightInput with light_type, optional name, location, energy, color, and type-specific settings (spot_size, size, etc.).

Returns: JSON with the light object name and properties.

Example: blender_add_light(light_type="POINT", location=(0, 0, 4), energy=2000)

Configure a camera's position, aim target, and focal length.

Uses the active scene camera if no name is given. Creates a new camera if the scene has none. Optionally points the camera at a 3D target point.

Args: params: SetCameraInput with optional name, location, target (point to aim at), lens (focal length in mm), and set_active flag.

Returns: JSON with the camera name, location, rotation, and lens.

Example: blender_set_camera(location=(5, -5, 3), target=(0, 0, 0), lens=50)

Render a frame using Blender's render engine and return the result inline.

Blocks until the render is complete. For fast previews use EEVEE; for photorealistic output use CYCLES (much slower — increase timeout_seconds).

Returns both a JSON metadata block and an inline image preview. If output_path is given the full-resolution render is also saved to disk.

Args: params: RenderImageInput with optional frame, output_path, engine override, Cycles sample override, preview size, and timeout.

Returns: List of [metadata JSON string, inline PNG preview Image].

Example: blender_render_image(engine="BLENDER_EEVEE", frame=1, max_preview_size=512) blender_render_image(engine="CYCLES", samples=64, timeout_seconds=600)

Execute arbitrary Python code inside Blender (escape hatch for advanced ops).

The code runs with bpy already imported. To return data, assign it to a variable named result. Use this only when no dedicated tool fits.

DESTRUCTIVE: arbitrary code can modify or delete anything in the scene.

Args: params: ExecutePythonInput with the code string to execute (max 20,000 chars).

Returns: JSON with the value of result (if set) or a success confirmation.

Example: code = "result = [obj.name for obj in bpy.data.objects if obj.type == 'MESH']"