Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

16.1 KB
Raw Blame

Blender MCP

@three-ws/blender-mcp hands an AI assistant the Blender installed on your own machine. It speaks the Model Context Protocol over stdio, and it drives Blender in background mode: no GUI session has to be open, no add-on has to be installed into Blender first, and nothing stays resident between calls.

That makes it the piece that sits under the three.ws pipeline rather than beside it. Forge generates a model; this reads it, converts it, previews it, and edits it, using the most complete format bridge that exists offline.


What it is for

You want to Tool
Know what is actually inside a file a client sent you blender_scene_info
Turn an FBX or a USD into a web-ready GLB (or the reverse) blender_convert
See a model without opening anything blender_render
Make a model small enough to ship, and see what it cost blender_optimize
Do something no single tool covers: join, rename bones, bake blender_run_python
Generate an asset from a sentence and open it blender_forge_import
Find out why one of the above failed blender_info

Requirements

  • Node.js 20+
  • Blender 3.0 or newer, installed locally: blender.org/download, or your package manager.

If Blender is not on PATH, set BLENDER_PATH to the executable. On macOS that is /Applications/Blender.app/Contents/MacOS/Blender.

Some Linux distribution packages ship Blender without the Python modules its glTF add-on needs. blender_info tells you what the local build can really do, which turns that class of problem into one clear answer instead of a confusing failure inside an unrelated call.


Install

Claude Code

claude mcp add blender -- npx -y @three-ws/blender-mcp

To run it straight from a checkout of this repository instead of the published package, add it to .mcp.json yourself. The entry is not committed: an MCP client rewrote that file in place on 2026-09-12 and dropped it, and the package it points at ships either way.

{
	"mcpServers": {
		"blender": {
			"command": "node",
			"args": ["packages/blender-mcp/src/index.js"]
		}
	}
}

Claude Desktop / Cursor

{
	"mcpServers": {
		"blender": {
			"command": "npx",
			"args": ["-y", "@three-ws/blender-mcp"],
			"env": { "BLENDER_PATH": "/Applications/Blender.app/Contents/MacOS/Blender" }
		}
	}
}

Tools

blender_info

No arguments. Reports the executable path, Blender version, bundled Python version, the render engines that are genuinely usable on this build, and the import/export extensions it supports. Read-only.

Call it first whenever anything else fails: it separates "Blender is missing" from "this build cannot do that" from "the file is wrong".

blender_scene_info

Argument Type Notes
input string, required Path to the file. Absolute, or relative to the server's working directory.
include_objects boolean Include the per-object breakdown. Set false on huge scenes for totals only. Default true.

Opens a .blend, or imports any supported format into an empty scene, and describes it: objects with type, parent, dimensions, modifiers, materials and UV layers; evaluated triangle and vertex counts, so a subdivision modifier is counted as what it renders, not what it stores; a texture inventory giving each image's resolution, format and byte size plus counts.texture_bytes, which against input_bytes is what tells you whether an asset is mesh-heavy or texture-heavy; armature bone names; animation actions with frame ranges; and world-space bounds. The file is never modified.

Counts describe the file as loaded. A GLB reports more vertices than the .blend it was exported from, because glTF splits vertices at UV and normal seams; the triangle count is identical either way.

blender_scene_info { "input": "~/assets/character.fbx" }

blender_convert

Argument Type Notes
input string, required Source file.
output string Destination. Its extension picks the format. Defaults to a .glb in the workdir.
apply_modifiers boolean Bake modifiers into the exported geometry. Default true.
scale number Uniform scale baked into the export, e.g. 0.01 for centimetres to metres.

Both sides accept .glb, .gltf, .fbx, .obj, .stl, .ply, .dae, .abc, .usd, .usda, .usdc, .usdz, .x3d, and .blend, as far as the local build supports them: several Linux distribution packages ship Blender without USD, Collada, or Alembic. blender_info lists what yours really has, and asking for one it lacks fails immediately with format_unsupported rather than part way through an export.

blender_convert { "input": "character.fbx", "output": "character.glb", "scale": 0.01 }

blender_optimize

Argument Type Notes
input string, required Model to optimize.
output string Destination. The extension picks the format. Defaults to a .glb in the workdir.
max_triangles integer Triangle budget for the whole scene. Omit to leave geometry alone.
max_texture_px integer Longest edge any texture may keep. Omit to leave textures alone.
compress enum meshopt (default), draco, or none. Applies to glTF output only.

The delivery pass, in one call. Decimation is collapse-based and applies one ratio across the whole scene, so meshes keep their relative density: a per-object budget is what flattens a face while leaving a wall at full resolution. Textures are scaled and repacked, unreferenced datablocks are dropped, and the mesh streams are compressed on the way out.

Compression runs outside Blender because Blender's exporter offers Draco only, and only on builds shipping the library, while meshopt is what the three.ws runtime and every major web viewer decode.

blender_optimize { "input": "character.glb", "output": "character-web.glb", "max_triangles": 30000, "max_texture_px": 1024 }

The response carries before and after counts, saved_bytes, saved_percent, and a steps array saying what each stage did, so the trade is visible instead of guessed. Vertex groups survive decimation, but check a heavily decimated skinned mesh with blender_render before shipping it.

blender_render

Argument Type Notes
input string, required File to render.
output string Destination PNG. Defaults into the workdir.
engine enum auto (default), CYCLES, BLENDER_EEVEE, BLENDER_WORKBENCH.
samples integer Default 32, enough for a preview.
resolution [width, height] Default [960, 960].
transparent boolean Transparent background instead of the world. Default false.
views integer How many angles to render, orbiting the model, 1 to 6. Default 1.
inline_image boolean Return the image inline so the assistant can see it. Default true.

Asking for several views orbits the model and renders every angle in the same Blender launch, one import for the whole set, and returns them all inline. Four views is what answers questions a single angle hides: whether the back is modelled at all, whether a texture only reads from the front. A multi-view set always orbits its own camera, so an authored camera is honoured only when views is 1.

The rendered image comes back inline as an MCP image block, downscaled to fit the caller's context, while the full-resolution PNG is written to disk. That is what makes a see-and-fix loop possible in one call, and it is the only way the render is reachable at all from a client with no filesystem access.

An asset file usually carries no camera and no lights, which is why rendering one straight out of a converter normally produces a black square. This tool fills both in: it creates a camera and frames it to the geometry's bounding sphere, and adds a key light and a lit world. A scene that already has its own camera and lighting is rendered exactly as authored, and the response says which of the two happened (camera_created, lights_created).

auto picks Cycles, which renders on CPU and therefore works in a container. EEVEE is far faster but needs a real GPU context.

blender_run_python

Argument Type Notes
code string, required Python to execute. bpy, math and Vector are already imported.
input string File to open first. Omit to start from an empty scene.
output string Export the result here afterwards; the extension picks the format.
apply_modifiers boolean Apply modifiers on that export. Default true.

Anything printed comes back as stdout. Assigning a JSON-serializable value to a variable named result returns it as structured data alongside the post-run scene counts.

blender_run_python {
  "input": "character.glb",
  "output": "character-lod1.glb",
  "code": "import bpy\nfor obj in bpy.data.objects:\n    if obj.type == 'MESH':\n        obj.modifiers.new('Decimate', 'DECIMATE').ratio = 0.5\nresult = {'meshes': len([o for o in bpy.data.objects if o.type == 'MESH'])}"
}

This tool runs caller-supplied code with the server's own permissions. See Security.

blender_forge_import

Argument Type Notes
prompt string One subject, e.g. a weathered brass diving helmet. Required unless an image is given; with an image it steers the reconstruction.
image string Local PNG, JPEG or WebP to reconstruct from. Uploaded straight to storage on a presigned PUT, so the bytes never pass through the API.
image_url string A public https image to reconstruct from, instead of uploading one.
output string Destination. .glb keeps the generated bytes untouched; any other extension converts on the way in.
tier enum draft, standard (default), high.
lane enum image (default, free), geometry (Meshy/Tripo, needs a key), sketch.
backend string Pin a backend. Omit to let the deployment choose for the tier.
aspect_ratio enum Reference image ratio. Default 1:1.

Runs the public /api/forge pipeline: the default image lane (FLUX to TRELLIS) is free and needs no key, wallet, or account. When the output asks for a non-GLB format, the untouched GLB is kept beside it as <name>.source.glb, because conversion is lossy for some targets and the original is what the rest of the three.ws pipeline consumes.

Generation runs on a shared GPU lane and typically takes tens of seconds to a couple of minutes. A reference image reconstructs in about the same time as a prompt.

If an upload fails, the deployment's object storage is the problem, not your file: image_url reaches the same lane without touching the upload path.

blender_forge_import { "prompt": "a weathered brass diving helmet", "output": "helmet.blend" }

Compressed glTF is decoded for you

Blender's glTF importer has no decoder for EXT_meshopt_compression. That matters more than it sounds: meshopt is what gltfpack emits and what most three.ws avatars ship as, so the platform's own primary delivery format fails in raw Blender with "Extension EXT_meshopt_compression is not available on this addon version". Draco is nominally supported, but only on builds that ship libextern_draco, which several Linux distribution packages omit.

Every tool that takes an input therefore decodes first, in process, using the same glTF libraries the rest of the repo depends on (@gltf-transform/core, meshoptimizer, draco3dgltf). There is no external binary to install, unlike the gltfpack path the GPU workers use (workers/rig/gltf_meshopt.py), because an npm package cannot assume one is present.

The response names what was decoded:

{ "decoded_compression": ["EXT_meshopt_compression"], "counts": { "triangles": 15744 } }

An uncompressed file is passed through untouched and the field is absent. Your file is never modified: the decoded copy lives in the job's scratch directory and dies with it.


How a call works

Every tool call spawns one process:

blender -b --factory-startup -noaudio --python src/py/runner.py -- <job.json> <result.json>

Three design decisions are worth knowing, because they are what makes the tools predictable:

  1. --factory-startup keeps your saved preferences and third-party add-ons out of the result, so the same conversion produces the same file on any machine.
  2. The runner writes its payload to a file, never to stdout. Blender prints progress, add-on chatter and render statistics on stdout; picking a payload out of that stream is guesswork. A missing result file is therefore an unambiguous "Blender died", and the error carries the log tail that says why.
  3. One process per call. A crashed job cannot corrupt the next one, and no state leaks between calls.

Every operator is resolved by name with fallbacks and every keyword is filtered against the operator's own RNA before the call, so the importer and exporter renames between Blender 3.x and 4.x do not break a tool.

Errors

Failures come back as structured tool errors, each naming a fix:

Code Meaning
blender_not_found No Blender on PATH or at the standard locations. Install it, or set BLENDER_PATH.
blender_too_old Found a Blender older than 3.0.
input_not_found The path does not exist or is unreadable.
format_unsupported This build has no importer or exporter for that extension. The message lists the ones it does have.
engine_unavailable The requested render engine is not in this build.
timeout The job passed BLENDER_MCP_TIMEOUT_MS and was killed.
blender_unusable A Blender executable exists but would not run. Carries per-candidate diagnostics; on a loaded machine this is usually transient and the call is worth retrying.
blender_crashed Blender exited without writing a result. The error carries its log tail.

Environment variables

Variable Default Purpose
BLENDER_PATH discovered Absolute path to the Blender executable.
BLENDER_MCP_TIMEOUT_MS 300000 Ceiling for one Blender job.
BLENDER_MCP_WORKDIR <tmpdir>/three-ws-blender-mcp Where outputs land with no explicit output path.
BLENDER_MCP_ALLOW_PYTHON 1 0 withdraws blender_run_python from the tool list entirely.
BLENDER_MCP_MAX_CONCURRENCY 2 Blender processes allowed at once; further calls queue.
BLENDER_MCP_INLINE_IMAGE_PX 768 Longest edge of the render copy returned inline.
BLENDER_MCP_INLINE_IMAGE_BYTES 1500000 Past this the image stays on disk and the response says so.
THREE_WS_BASE https://three.ws Deployment backing blender_forge_import.
THREE_WS_FORGE_TIMEOUT_MS 600000 Ceiling for one generation.
THREE_WS_FORGE_PROVIDER_KEY unset Meshy/Tripo key for the bring-your-own-key geometry lane.

Security

blender_run_python executes caller-supplied Python inside Blender with this server's permissions, including filesystem access. That is what the tool is for, and it is annotated destructiveHint: true so a client prompts before running it. For unattended or shared deployments set BLENDER_MCP_ALLOW_PYTHON=0: the tool is then never advertised, and the other six keep working.

Only blender_forge_import reaches the network, and only the deployment named by THREE_WS_BASE. Everything else stays on the machine. The broader model is in MCP safety.


Related

  • integrations/blender/ is the artist-facing counterpart: a Blender add-on with a sidebar panel that generates three.ws models from inside the GUI. This server is the agent-facing one; they can be installed side by side.
  • MCP integration lists every three.ws MCP server.
  • 3D API documents the Forge endpoints behind blender_forge_import.
  • Scenes MCP composes whole 3D worlds from one sentence.