blender-mcp
Allows agents to see and drive a running Blender instance through its MCP addon socket. Provides tools for lifecycle control, scene and object inspection, running Python with bpy, taking viewport screenshots, rendering/turntable views in multiple modes, importing/exporting GLB/glTF assets, managing rigs and poses, running range-of-motion tests, and comparing renders against reference silhouettes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@blender-mcp render a 4-view turntable of the scene and show me the images"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Is the addon socket reachable? |
| Launch Blender (optionally opening a file) and wait until the addon answers. No-op if already up |
| Quit Blender. Refuses if the file has unsaved changes unless |
Inspect / script
Tool | What it does |
| Objects, counts, transforms, materials |
| Run Python in Blender ( |
| Viewport screenshot as an image (Blender UI must be open) |
Rendering (all return images; the scene is restored afterwards)
Tool | What it does |
| Evenly spaced views of all visible meshes. View 0 = front (-Y) |
| Explicit camera views (az 0 = front, +az toward +X; el = elevation); |
| Render through the scene's own camera and lights (shot rendering): |
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 |
| Import GLB/glTF/FBX; returns new objects, triangle count, dimensions (m) |
| Export the scene or the listed objects |
| Open / save a .blend, clear the scene |
| Run an external asset validator (see below) |
Rig / range of motion
Tool | What it does |
| Bones (parent, head/tail) and bound meshes |
| Pose by world direction ( |
| Animation: jump to a frame, aim a pose, key it; repeat for each key, then render with |
| Local Euler rotations in degrees per bone (needs bone-axis knowledge) |
| Deformation of the current pose vs rest: face-area ratio percentiles, fraction stretched >2x / squashed <0.4x, volume ratio, zero-weight vertices |
| 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 |
Likeness
Tool | What it does |
| 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 syncClaude Code
claude mcp add blender -- uv --directory /path/to/blender-mcp run python -m blender_mcp.serveropencode / 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 |
|
| Host running Blender |
|
| Addon socket port |
| unset | Path to a |
|
| ComfyUI instances sharing the GPU (GPU guard) |
|
| GPU guard threshold |
| auto | Path to |
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 pytestUnit 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 toolsblender_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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Generate 3D models, worlds, PBR materials, and coordinated asset packs from AI agents.
3D avatar/asset foundry: text/image -> rigged, validated, engine-ready GLB via x402.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to drive a live Blender session for modeling, shading, lighting, rendering, and scene manipulation, returning rendered images for visual feedback.4122MIT
- AlicenseAqualityBmaintenanceEnables 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.113MIT
- AlicenseNot gradedqualityCmaintenanceLets 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
- AlicenseNot gradedqualityBmaintenanceEnables 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.1BSD 3-Clause