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.
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:
--factory-startupkeeps your saved preferences and third-party add-ons out of the result, so the same conversion produces the same file on any machine.- 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.
- 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.