uniset-blender-mcp
v0.2.0
Published
Uniset use Blender: local MCP server that drives a background Blender process, with offline Blender craft skills and kits for scene blocking, toon materials and generated textures.
Readme
Uniset use Blender
Local MCP server that controls a dedicated background Blender process. No add-on, network listener, account or open Blender window is required.
Desktop MCP client → stdio → Node MCP server → process pipes → Blender --background → bpyEach MCP connection owns one Blender process. Its scene persists between commands; it cannot see unsaved work in an open desktop Blender. Open saved input with bl_open_project, edit and render, then save a .blend output and open it in desktop Blender. Disconnecting loses unsaved session changes.
Used by the Uniset MCP workflows /use-blender, /exploded-view, /destruction-studio, /scene-builder and /cartoon-shaders (served by the Uniset connector, https://mcp.uniset.ai/mcp).
Requirements
- Node.js 24 or later with npm.
- Blender 4.2 or later on the same computer as the MCP client.
- An MCP client with a shell on that computer: Claude Code (including Claude Desktop Code → Local) or local Codex.
Installation
blenderDir="$HOME/.uniset/blender-mcp" # Windows: %LOCALAPPDATA%\Uniset\blender-mcp
npm install --prefix "$blenderDir" uniset-blender-mcp@latest
blenderCli="$blenderDir/node_modules/uniset-blender-mcp/dist/cli.js"
node "$blenderCli" doctor --blender "/absolute/path/to/blender"
node "$blenderCli" config --blender "/absolute/path/to/blender" --format jsonRegister the printed entry, for Claude Code:
claude mcp add --scope user uniset-use-blender --env "BLENDER_EXECUTABLE=/absolute/path/to/blender" -- /absolute/path/to/node /absolute/path/to/dist/index.jsThen start a new session: MCP servers are loaded when a session starts. Full guidance: skills/use-blender/.
Tools
| Area | Tools |
| --- | --- |
| Inspect | bl_health, bl_get_scene_summary, bl_get_object |
| Scene | bl_add_primitive, bl_delete_object, bl_set_transform, bl_set_material, bl_import_model |
| Camera/light | bl_add_camera, bl_set_active_camera, bl_add_light |
| Animation | bl_set_frame, bl_insert_keyframe |
| Files | bl_save_project, bl_open_project |
| Evidence | bl_render |
| Python/status | bl_execute, bl_job_status |
| Offline guidance | bl_list_skills, bl_get_skill, bl_get_skill_asset |
Start with bl_get_skill(name: "blender-scene").
Skills and kits
| Task | Skill | Bundled kit |
| --- | --- | --- |
| Exploded views and assembly animations | blender-camera-led-assembly | |
| Building collapse with rigid bodies | blender-destruction | |
| Rooms, furniture, mannequin actors, shot cameras | blender-scene-blocking | assets/stage_kit.py |
| Cartoon, comic and illustration materials with outlines | blender-toon-materials | assets/toon_kit.py |
| Generated environment panorama and tileable materials (through the Uniset connector) | blender-generation, blender-hdri, blender-pbr | blender-generation/assets/texture_kit.py |
A kit is a single Python file run inside the background Blender: bl_get_skill_asset returns its path and the skill shows how to load it in bl_execute. Kits build native Blender data (meshes, armatures, node groups, modifiers), install no add-on and download nothing; the saved .blend does not need the kit to open or render. Generation itself is not part of this package: it is done by the Uniset connector and spends the user's tokens only on request.
Long commands
A command that outlives its time limit returns state: "running" and a job_id; the job keeps running. Poll bl_job_status on the same connection until state is completed. Do not close the connection meanwhile: closing it stops Blender together with the job.
| Variable | Default | Meaning |
| --- | --- | --- |
| BLENDER_EXECUTABLE | standard locations, then PATH | Absolute path to the Blender executable |
| BLENDER_MCP_TIMEOUT_SECONDS | 120 | Per-call limit before a command reports running |
| BLENDER_MCP_RENDER_TIMEOUT_SECONDS | 300 | The same for bl_render |
| BLENDER_MCP_GPU | on | off keeps Cycles on the CPU (for a misbehaving GPU driver) |
GPU rendering
The background Blender starts with factory settings, where Cycles has no compute device: a scene saved with cycles.device = 'GPU' would silently render on the CPU. At startup the server enables the first available backend (OptiX, CUDA, HIP, oneAPI, Metal) in that process's in-memory preferences; the user's saved preferences are never touched. bl_health and doctor report it as gpu (null: CPU only). The scene's own cycles.device still decides whether it renders on the GPU. Measured on an RTX 3050 Laptop: one 1080p Cycles frame 10.8 s with the GPU, 67.4 s without.
Limits
Python runs sequentially on Blender's main thread and is not sandboxed. stdout/stderr are capped at 64 Ki characters each; JSON results at 4 MiB. Save/render refuse existing outputs unless overwrite: true; opening another project refuses unsaved changes unless explicitly discarded. Automatic execution of Python embedded in opened .blend files is disabled. If Blender crashes, the session is not restarted automatically.
Testing
npm run test:live starts the server against a real Blender (BLENDER_EXECUTABLE) and checks the tool list, a render, the running result of a long command, bl_job_status, the Cycles GPU, and each bundled kit (a room with an actor and a camera, a toon material with its outline, a seam repair with derived maps). Set SMOKE_EXPECT_GPU=1 on a machine with a GPU to make a missing one a failure.
License
MIT. Fork of Higgsfield fnf-blender-mcp 0.2.2; see UPSTREAM.md and LICENSE.
