Headless Blender — 3D modelling and GLB export
pi-blender runs the published Blender WebAssembly build inside Node: no native Blender, no GUI, no GPU.
The runtime (~175 MB) is downloaded once, verified against a pinned hash, and cached. It is a stdio MCP
server (blender-wasm) with one persistent Blender session per server.
When to use it
- Build or edit 3D geometry with Python (
bpy): primitives, modifiers, materials, hierarchies.
- Convert or inspect 3D files:
.glb .gltf .fbx .obj .stl .ply .svg .blend.
- Produce a
.glb for a web viewer, game engine or AR.
Not for rendering images (no rendering here) or for anything needing a GUI.
Setup (once per machine, once per project)
pi-blender ensure # download + verify the runtime NOW; otherwise the first tool call is slow
pi-blender status # what is cached, JSPI support (never downloads)
pi-blender mcp --register # in the project root: writes .pi/mcp.json -> "blender-wasm"
pi-blender mcp --register --root assets # confine file access to ./assets instead of the project
Registration is opt-in and project-local; pi loads project MCP servers only after the project is trusted,
and only when started in the project root. ensure needs Node 24 or newer (WebAssembly JSPI); on
older Node it exits 69 saying so — do not retry, tell the user to use Node 24+.
Tools
| Tool |
Use |
blender_scene |
List objects (name, type, parent, transform, dimensions, materials, mesh counts). limit default 200. Start here to see what exists. |
blender_python |
Run bpy Python. inputs stages root-relative files at /in/<same path>; anything written under /out/ is saved to outputDir (default blender-out). print() output is returned. |
blender_import |
Import one file by extension. A .blend replaces the whole scene. |
blender_export |
Export the scene by extension of the target path. selectedOnly exports the selection (not for .blend). |
blender_reset |
mode: "factory" (default cube/light/camera scene) or "empty". |
All paths are relative to the confined root; a path outside it fails with path-outside-root.
Build limits (do not plan around these)
- Single-threaded Blender 5.3 alpha under WebAssembly, EEVEE only: no rendering.
- No Subsurf / OpenSubdiv, no Draco or meshopt compression.
- No USD, Alembic or X3D import/export.
- No network and no subprocess from Python (
fetch, sockets and process spawning are unavailable).
- About 1.2 GB of memory per live session. Keep one server per project; sessions end after idle time
(
BLENDER_WASM_IDLE_SEC, default 600).
- Subdivide with explicit geometry (
bmesh, loop cuts, array/bevel modifiers) instead of Subsurf.
sessionReset: true means the scene was lost
Every tool result is JSON starting with {"sessionReset": …}. It is true on the first result after a live
session was lost (timeout, crash, out-of-memory, idle expiry): the scene is gone and everything not
exported with blender_export is gone. A timeout or session-crashed error means the same thing even
though its own flag is still false. Say so, run blender_scene to see the fresh state, and rebuild from a
script — never assume objects still exist. After a timeout or session-crashed, shrink the work (fewer
vertices, smaller modifiers) rather than repeating it. Export a .blend between big steps.
GLB-first workflow
blender_reset with mode: "empty" (a factory scene brings a cube, light and camera into the export).
- Build with one
blender_python script that is idempotent (clear/rebuild by name) so it can be re-run.
blender_scene to check object count, dimensions and materials.
blender_export to models/thing.glb. Prefer .glb — one self-contained file. Verify the file is on disk.
- Only then offer other formats (
.fbx, .obj + .mtl, .stl, .ply, .blend).
Multi-file assets and .gltf
blender_import takes ONE file. For anything that references siblings (OBJ + MTL + textures, glTF with
.bin/images, FBX with textures) use blender_python with inputs listing every file:
# inputs: ["assets/chair.obj", "assets/chair.mtl", "assets/wood.png"]
import bpy
bpy.ops.wm.obj_import(filepath="/in/assets/chair.obj")
A .gltf exported by blender_export is .gltf + .bin; re-import it the same way
(inputs: ["m/a.gltf", "m/a.bin"], bpy.ops.import_scene.gltf(filepath="/in/m/a.gltf")).
blender_import of a .gltf only works when everything is embedded as data: URIs.
Headless bpy idioms
- Files: read from
/in/..., write to /out/... (the only places visible to the session). Subdirectories
under /out are kept.
- Link every new object yourself:
bpy.context.collection.objects.link(obj). Prefer the data API
(bpy.data.meshes.new, bmesh) over bpy.ops.mesh.primitive_* when a context is awkward.
- Avoid operators that need a window, area or region (viewport, UI,
view3d, screen, *_modal); they
fail headless. Select with obj.select_set(True) and bpy.context.view_layer.objects.active = obj
instead of UI calls, and check an operator's return value ({'FINISHED'}).
- Name things (
obj.name, mat.name) so blender_scene output is readable and scripts can find them.
- Apply scale before export (
bpy.ops.object.transform_apply(scale=True) with the object active).
print() what you need to see; output beyond ~16 KiB is truncated (outputTruncated: true).
- Python errors come back as
python-error with a traceback tail: fix and re-run, the session is still alive
(sessionReset: false).
Errors
invalid-arguments, jspi-unavailable (Node < 24), provision-failed (run pi-blender ensure and read
its message), boot-failed, path-outside-root, input-not-found, unsupported-format, limit-exceeded
(input/output size caps: BLENDER_WASM_MAX_INPUT_MB / BLENDER_WASM_MAX_OUTPUT_MB can only lower them),
python-error, import-failed, export-failed, timeout, session-crashed.
1---2name: blender-23description: Headless Blender (bpy) for 3D modelling and GLB export, with no native Blender install - build or edit a scene in Python, import OBJ/FBX/STL/PLY/glTF/.blend, export .glb and other formats, all through the blender-wasm MCP server and the pi-blender CLI. Use for "model a 3D object", "make a .glb of this", "convert this OBJ/FBX to glTF", "inspect this 3D model".4metadata:5 source: https://skillmd.com/skills/majiayu000/blender-26---78# Headless Blender — 3D modelling and GLB export910`pi-blender` runs the published Blender WebAssembly build inside Node: no native Blender, no GUI, no GPU.11The runtime (~175 MB) is downloaded once, verified against a pinned hash, and cached. It is a **stdio MCP12server** (`blender-wasm`) with one persistent Blender session per server.1314## When to use it1516- Build or edit 3D geometry with Python (`bpy`): primitives, modifiers, materials, hierarchies.17- Convert or inspect 3D files: `.glb` `.gltf` `.fbx` `.obj` `.stl` `.ply` `.svg` `.blend`.18- Produce a **`.glb`** for a web viewer, game engine or AR.1920Not for rendering images (no rendering here) or for anything needing a GUI.2122## Setup (once per machine, once per project)2324```bash25pi-blender ensure # download + verify the runtime NOW; otherwise the first tool call is slow26pi-blender status # what is cached, JSPI support (never downloads)27pi-blender mcp --register # in the project root: writes .pi/mcp.json -> "blender-wasm"28pi-blender mcp --register --root assets # confine file access to ./assets instead of the project29```3031Registration is opt-in and project-local; pi loads project MCP servers only after the project is trusted,32and only when started in the project root. `ensure` needs **Node 24 or newer** (WebAssembly JSPI); on33older Node it exits 69 saying so — do not retry, tell the user to use Node 24+.3435## Tools3637| Tool | Use |38|------|-----|39| `blender_scene` | List objects (name, type, parent, transform, dimensions, materials, mesh counts). `limit` default 200. **Start here** to see what exists. |40| `blender_python` | Run `bpy` Python. `inputs` stages root-relative files at `/in/<same path>`; anything written under `/out/` is saved to `outputDir` (default `blender-out`). `print()` output is returned. |41| `blender_import` | Import one file by extension. A `.blend` **replaces the whole scene**. |42| `blender_export` | Export the scene by extension of the target path. `selectedOnly` exports the selection (not for `.blend`). |43| `blender_reset` | `mode: "factory"` (default cube/light/camera scene) or `"empty"`. |4445All paths are relative to the confined root; a path outside it fails with `path-outside-root`.4647## Build limits (do not plan around these)4849- Single-threaded **Blender 5.3 alpha** under WebAssembly, EEVEE only: **no rendering**.50- **No Subsurf / OpenSubdiv**, no Draco or meshopt compression.51- **No USD, Alembic or X3D** import/export.52- **No network and no subprocess** from Python (`fetch`, sockets and process spawning are unavailable).53- About **1.2 GB of memory per live session**. Keep one server per project; sessions end after idle time54 (`BLENDER_WASM_IDLE_SEC`, default 600).55- Subdivide with explicit geometry (`bmesh`, loop cuts, array/bevel modifiers) instead of Subsurf.5657## `sessionReset: true` means the scene was lost5859Every tool result is JSON starting with `{"sessionReset": …}`. It is `true` on the **first result after a live60session was lost** (timeout, crash, out-of-memory, idle expiry): **the scene is gone** and everything not61exported with `blender_export` is gone. A `timeout` or `session-crashed` error means the same thing even62though its own flag is still `false`. Say so, run `blender_scene` to see the fresh state, and rebuild from a63script — never assume objects still exist. After a `timeout` or `session-crashed`, shrink the work (fewer64vertices, smaller modifiers) rather than repeating it. Export a `.blend` between big steps.6566## GLB-first workflow67681. `blender_reset` with `mode: "empty"` (a factory scene brings a cube, light and camera into the export).692. Build with one `blender_python` script that is **idempotent** (clear/rebuild by name) so it can be re-run.703. `blender_scene` to check object count, dimensions and materials.714. `blender_export` to `models/thing.glb`. Prefer `.glb` — one self-contained file. Verify the file is on disk.725. Only then offer other formats (`.fbx`, `.obj` + `.mtl`, `.stl`, `.ply`, `.blend`).7374## Multi-file assets and `.gltf`7576`blender_import` takes ONE file. For anything that references siblings (OBJ + MTL + textures, glTF with77`.bin`/images, FBX with textures) use `blender_python` with `inputs` listing **every** file:7879```python80# inputs: ["assets/chair.obj", "assets/chair.mtl", "assets/wood.png"]81import bpy82bpy.ops.wm.obj_import(filepath="/in/assets/chair.obj")83```8485A `.gltf` exported by `blender_export` is `.gltf` + `.bin`; re-import it the same way86(`inputs: ["m/a.gltf", "m/a.bin"]`, `bpy.ops.import_scene.gltf(filepath="/in/m/a.gltf")`).87`blender_import` of a `.gltf` only works when everything is embedded as `data:` URIs.8889## Headless `bpy` idioms9091- Files: read from `/in/...`, write to `/out/...` (the only places visible to the session). Subdirectories92 under `/out` are kept.93- Link every new object yourself: `bpy.context.collection.objects.link(obj)`. Prefer the data API94 (`bpy.data.meshes.new`, `bmesh`) over `bpy.ops.mesh.primitive_*` when a context is awkward.95- Avoid operators that need a window, area or region (viewport, UI, `view3d`, `screen`, `*_modal`); they96 fail headless. Select with `obj.select_set(True)` and `bpy.context.view_layer.objects.active = obj`97 instead of UI calls, and check an operator's return value (`{'FINISHED'}`).98- Name things (`obj.name`, `mat.name`) so `blender_scene` output is readable and scripts can find them.99- Apply scale before export (`bpy.ops.object.transform_apply(scale=True)` with the object active).100- `print()` what you need to see; output beyond ~16 KiB is truncated (`outputTruncated: true`).101- Python errors come back as `python-error` with a traceback tail: fix and re-run, the session is still alive102 (`sessionReset: false`).103104## Errors105106`invalid-arguments`, `jspi-unavailable` (Node < 24), `provision-failed` (run `pi-blender ensure` and read107its message), `boot-failed`, `path-outside-root`, `input-not-found`, `unsupported-format`, `limit-exceeded`108(input/output size caps: `BLENDER_WASM_MAX_INPUT_MB` / `BLENDER_WASM_MAX_OUTPUT_MB` can only lower them),109`python-error`, `import-failed`, `export-failed`, `timeout`, `session-crashed`.