Skip to main content
Glama

blender-mcp

An MCP server that lets agents see and drive a running Blender: take viewport screenshots, render turntable views, inspect the scene and run Python. It talks to the socket of the Blender MCP addon (default 127.0.0.1:9876).

The point: an agent that can look at a 3D result can judge its quality instead of guessing.

Tools

Lifecycle

Tool

What it does

blender_status

Is the addon socket reachable?

blender_start(blend_file, timeout)

Launch Blender (optionally opening a file) and wait until the addon answers. No-op if already up

blender_stop(force)

Quit Blender. Refuses if the file has unsaved changes unless force=True (kills it)

Inspect / script

Tool

What it does

blender_scene_info, blender_object_info(name)

Objects, counts, transforms, materials

blender_run_python(code, timeout)

Run Python in Blender (bpy). The reply is the code's stdout, so use print()

blender_screenshot(max_size)

Viewport screenshot as an image (Blender UI must be open)

Rendering (all return images; the scene is restored afterwards)

Tool

What it does

blender_turntable(views, size, elevation, mode, ...)

Evenly spaced views of all visible meshes. View 0 = front (-Y)

blender_render(views=[{az, el}], size, mode, ortho, objects, focus, ...)

Explicit camera views (az 0 = front, +az toward +X; el = elevation); focus frames a world-space region

blender_render_scene(width, height, mode, frames, objects, hide, ...)

Render through the scene's own camera and lights (shot rendering): beauty, per-object mask, normal; hide actors for a clean plate

mode: material (scene materials + temporary offset key light), solid (Workbench, fast), wireframe (Cycles on CPU; needs enough pixels per polygon to show lines), normal (world-space, rgb = n*0.5+0.5), mask (RGBA, silhouette in alpha). material/normal/mask use the GPU, see GPU guard.

Files / assets

Tool

What it does

blender_import_glb(path)

Import GLB/glTF/FBX; returns new objects, triangle count, dimensions (m)

blender_export_glb(path, objects)

Export the scene or the listed objects

blender_open(path), blender_save(path), blender_new_scene(keep)

Open / save a .blend, clear the scene

blender_validate_asset(glb_path, height_m, tri_budget, ...)

Run an external asset validator (see below)

Rig / range of motion

Tool

What it does

blender_rig_info(armature)

Bones (parent, head/tail) and bound meshes

blender_pose_aim(armature, aim)

Pose by world direction ({"RightArm": [1, 0, 0.2]}): each bone's limb (its head to its child's head, not its tail) points that way. Returns residual degrees per bone. Preferred way to author poses

blender_key_pose(armature, frame), blender_timeline(start, end, fps, frame)

Animation: jump to a frame, aim a pose, key it; repeat for each key, then render with blender_render_scene(frames=[...])

blender_set_pose(armature, rotations), blender_reset_pose

Local Euler rotations in degrees per bone (needs bone-axis knowledge)

blender_pose_metrics(armature, mesh)

Deformation of the current pose vs rest: face-area ratio percentiles, fraction stretched >2x / squashed <0.4x, volume ratio, zero-weight vertices

blender_rom_test(armature, mesh, poses, ...)

For each pose: apply, measure, render; JSON report + one image per pose; rig reset afterwards. The built-in Mixamo pose table has uncalibrated axes: check the images or pass your own poses

Likeness

Tool

What it does

blender_compare_ref(ref_image, azimuth, elevation)

Silhouette IoU between an orthographic mask render and a reference image, plus proportion mismatch and an overlay image. Coarse: both silhouettes are cropped to their bounding boxes

Paths: /mnt/<drive>/... (WSL) is converted to D:\... when the server runs on Windows.

Related MCP server: bl-mcp

Requirements

  • Blender with the MCP addon enabled and its server listening (default port 9876)

  • Python >= 3.10 and uv

Install

git clone https://github.com/thanhdoancong127/blender-mcp.git
cd blender-mcp
uv sync

Claude Code

claude mcp add blender -- uv --directory /path/to/blender-mcp run python -m blender_mcp.server

opencode / other stdio clients

Register a stdio server whose command is uv --directory /path/to/blender-mcp run python -m blender_mcp.server.

Configuration

Env var

Default

Meaning

BLENDER_MCP_HOST

127.0.0.1

Host running Blender

BLENDER_MCP_PORT

9876

Addon socket port

ASSET_VALIDATOR_PY

unset

Path to a validate_asset.py exposing validate(path, height_m, tri_budget, tol, nonmanifold_max) (and optionally validate_with_doc). Its deps: uv sync --extra validate

COMFY_URLS

http://127.0.0.1:8188,http://127.0.0.1:8189

ComfyUI instances sharing the GPU (GPU guard)

MIN_FREE_VRAM_GB

6

GPU guard threshold

BLENDER_EXE

auto

Path to blender.exe; default is the newest install under Program Files\Blender Foundation

WSL note

If Blender runs on Windows and the server runs in WSL, 127.0.0.1 in WSL does not reach the Windows loopback. Either run the server with the Windows Python (so it connects locally), or point BLENDER_MCP_HOST at an address the addon is reachable on.

GPU guard

If ComfyUI shares the GPU, GPU renders (material, normal, mask) are refused while a ComfyUI job is running or free VRAM is below MIN_FREE_VRAM_GB; pass ignore_gpu_guard=True to override. solid and wireframe do not use the GPU. An unreachable ComfyUI is treated as idle.

Safety

blender_run_python executes arbitrary code in your Blender session. Keep the addon bound to localhost and do not expose its port to a network. The addon handles one command at a time; this client serializes calls, and heavy renders may need a larger timeout.

Tests

uv sync --extra validate --group dev
uv run pytest

Unit tests cover the socket protocol against a fake addon, path conversion, the GPU guard, silhouette comparison, the validator bridge and syntax of every Blender snippet. They do not run Blender.

Verified by hand against Blender 5.2 on Windows (through a real stdio MCP client): lifecycle, all render modes, import/export, save/open, rig + pose metrics + ROM on a synthetic skinned tube, silhouette compare, a 1.3M-triangle model (turntable < 2 s, GLB 135 MB, import 6.5 s) and the timeout path. Not yet verified: real character rigs (the Mixamo pose table), Cycles GPU renders and the GPU guard against a busy ComfyUI.

License

MIT

Available Tools

25 tools
blender_compare_refB

Coarse likeness check: silhouette IoU between an orthographic render of the model (from azimuth/ elevation) and a reference image (alpha, or plain background). Both are cropped to their bounding boxes, so position/scale are ignored; aspect_ratio_diff reports proportion mismatch. Returns JSON and an overlay image (red = reference only, green = render only, yellow = both).

Inputs: ref_image (required), azimuth, objects, elevation.

blender_export_glbA

Export to a .glb. With objects, only those; otherwise the whole scene.

Inputs: path (required), objects.

blender_import_glbB

Import a GLB/glTF/FBX into the open scene. Returns new objects, triangle count and dimensions (x,y,z in m).

Inputs: path (required).

blender_key_poseA

Keyframe the current pose of the armature at frame (all bones, plus the object's location/rotation). Workflow for a clip: blender_timeline(frame=f) -> blender_pose_aim(...) -> blender_key_pose(frame=f), repeat.

Inputs: frame (required), armature (required), with_object.

blender_new_sceneB

Remove all objects (orphan data purged). keep: object types to keep, e.g. ["CAMERA", "LIGHT"].

Inputs: keep.

blender_object_infoC

Transform, dimensions, materials and mesh stats for one object.

Inputs: object_name (required).

blender_openC

Open a .blend (replaces the current scene; unsaved changes are lost).

Inputs: path (required).

blender_pose_aimA

Pose by direction, no bone-axis knowledge needed: aim={"RightArm": [1, 0, 0.2], "Spine": [0, 0, 1]} points each bone's limb (its head to the head of its continuing child, not the bone tail) along that WORLD direction, parents first. Returns the residual angle per bone in degrees. Prefer this over blender_set_pose for authoring poses.

Inputs: aim (required), armature (required), reset.

blender_pose_metricsB

Deformation metrics of the CURRENT pose vs rest: face-area ratio percentiles, fraction of faces stretched >2x or squashed <0.4x, volume ratio (volume loss = candy-wrapper joints), and the number of vertices with zero skin weight.

Inputs: mesh (required), armature (required).

blender_renderB

Render explicit camera views: views=[{"az": degrees, "el": degrees}, ...] (az 0 = front/-Y, +az toward +X, el = elevation). objects limits the framed/rendered meshes; ortho=True gives an orthographic camera. focus={"center": [x, y, z], "radius": r} frames that world-space region (e.g. the head of a full body). Modes as in blender_turntable. Returns the images.

Inputs: views (required), mode, size, focus, +6 more.

blender_render_sceneB

Render through the scene's OWN active camera and lights (shot rendering), one image per frame. mode: beauty | mask (needs objects: only they are drawn, white, silhouette in alpha) | normal. hide hides objects for this render (e.g. actors -> clean background plate). Returns the images.

Inputs: hide, mode, width, engine, +5 more.

blender_reset_poseC

Return all pose bones of the armature to the rest pose.

Inputs: armature (required).

blender_rig_infoC

Bones (name, parent, head/tail in rest pose) of an armature and the meshes bound to it.

Inputs: armature (required).

blender_rom_testA

Range-of-motion test: for each pose apply it, measure deformation and render. Returns a JSON report followed by one image per pose; the rig is reset to rest afterwards.

poses={"name": {"bone": [x, y, z]}} in degrees. Default is a Mixamo-named table whose rotation axes are NOT calibrated: check the images and pass your own poses if they look wrong.

Inputs: mesh (required), armature (required), mode, size, +3 more.

blender_run_pythonB

Run Python inside Blender (bpy available). The reply is the code's stdout: use print().

Executes arbitrary code in the user's Blender session. Keep edits reproducible: record meaningful changes in your build scripts, not only in the live scene.

Inputs: code (required), timeout.

blender_saveB

Save the current file, or save as path when given.

Inputs: path.

blender_scene_infoB

Summary of the open Blender scene (objects, counts, active camera).

Inputs: no named parameters.

blender_screenshotB

Screenshot of the Blender 3D viewport (needs the Blender UI open). Returns an image.

Inputs: max_size.

blender_set_poseA

Set local Euler rotations (degrees) on pose bones: rotations={"bone": [x, y, z]}. reset=True clears other bones first. Use blender_reset_pose afterwards to go back to rest.

Inputs: armature (required), rotations (required), reset.

blender_startB

Launch Blender (optionally opening blend_file) and wait until the addon socket answers.

No-op if it is already up. Finds blender.exe in Program Files or via $BLENDER_EXE.

Inputs: timeout, blend_file.

blender_statusB

Is Blender's MCP addon socket reachable right now?

Inputs: no named parameters.

blender_stopA

Quit Blender. Refuses when the file has unsaved changes unless force=True (which kills it).

Inputs: force.

blender_timelineB

Set the frame range / fps and/or jump to a frame (which evaluates existing keyframes).

Inputs: end, fps, frame, start.

blender_turntableA

Render evenly spaced turntable views of all visible meshes; returns the images. View 0 = front (-Y).

mode: material (scene materials + temporary offset key light of strength light), solid (Workbench, fast), wireframe (Cycles on CPU), normal (world-space), mask (alpha silhouette). solid and wireframe skip the GPU guard. The scene is restored. Refuses to render while ComfyUI is running a job or VRAM is low, unless ignore_gpu_guard=True.

Inputs: mode, size, light, views, +4 more.

blender_validate_assetA

Run the asset validator (dims within tol of height_m, tri budget, NaN, zero-area faces, non-manifold, PBR maps). With asset_json also cross-checks the sidecar. Needs ASSET_VALIDATOR_PY (see README).

Inputs: glb_path (required), height_m (required), tri_budget (required), tol, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools target clearly distinct operations, and the render family (blender_turntable, blender_render, blender_render_scene) is carefully differentiated by camera source. The pose tools (blender_set_pose vs blender_pose_aim) overlap slightly, but descriptions explicitly state when to prefer each.

    Naming Consistency5/5

    Every tool uses the same blender_ snake_case prefix, and names read as clear verb_noun or noun_noun constructs. Minor verb-placement variation (blender_render_scene vs blender_scene_info) does not break the pattern.

    Tool Count4/5

    25 tools is on the heavy side, but the surface genuinely spans several subdomains (file/lifecycle, rendering, rigging/posing, validation). Each tool maps to a distinct capability rather than redundant variants.

    Completeness4/5

    The set covers lifecycle (start/stop/status, open/save/new), import/export, scene/object inspection, rendering, rigging/posing/keyframing, and validation/comparison. Gaps like direct object deletion or material editing exist but are largely workable via blender_run_python.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to drive a live Blender session for modeling, shading, lighting, rendering, and scene manipulation, returning rendered images for visual feedback.
      4
      122
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI agent to drive a live Blender session, building, sculpting, measuring, checking, rigging, lighting, rendering and exporting 3D models through safe operations in world units. Every geometry-changing call reports achieved dimensions, open edges and failures as numbers and review images, so modelling mistakes become visible instead of silent.
      113
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets an AI engine drive a Blender instance the user runs themselves over stdio JSON-RPC, enabling scene inspection, viewport capture and picking, sandboxed code execution, and gated asset search/import and 3D generation. Telemetry is disabled before import, outbound tools are withheld until per-run network consent, and VRAM gating plus a surface-policy tool report what is live and what a station has cleared.
      Business Source 1.1
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP hosts and coding agents to model, inspect, measure, and deliver real Blender scenes through 15 tools and 217 catalog operations, returning actual rendered images after key edits. Works against a live Blender GUI via addon or a persistent headless worker, producing editable .blend files, GLB exports, previews, and acceptance records.
      1
      BSD 3-Clause