Higgsfield Blender MCP

Local MCP server that controls a dedicated background Blender process. No add-on, HTTP listener, WebSocket, cloud account or open Blender window is required.

Desktop MCP client → stdio → Node MCP → process pipes → Blender --background → bpy

Each MCP connection owns one process. Its scene persists between commands; it cannot access unsaved work in an already-open desktop Blender. Open saved input with bl_open_project, edit and render, then save a .blend output to inspect in the desktop UI. Disconnecting loses unsaved session changes.

Requirements

• Node.js 24 or later with npm.
• Blender 4.2 or later on the same computer as the MCP client.

Installation

blenderDir="$HOME/.higgsfield/blender-mcp"
npm install --prefix "$blenderDir" fnf-blender-mcp@latest
blenderCli="$blenderDir/node_modules/fnf-blender-mcp/dist/cli.js"
node "$blenderCli" doctor --blender "/absolute/path/to/blender"
node "$blenderCli" config --blender "/absolute/path/to/blender" --format json

Use the executable inside Blender.app/Contents/MacOS/Blender on macOS, or blender.exe on Windows. config --format toml prints a Codex entry. Both formats include absolute Node/server paths and BLENDER_EXECUTABLE; merge the entry into the intended client and refresh its connection. The helper prints configuration but does not register a server. The installed package includes a use-blender skill with additional setup guidance.

The server starts Blender on its first execution call. doctor checks a separate temporary background process and terminates it afterward. Verify conversation access with bl_health and bl_get_scene_summary. BLENDER_EXECUTABLE can be set directly; without it the runtime tries standard installation locations and PATH. No separate Python installation is needed at runtime.

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"). Python runs sequentially on the process's main thread. Scene datablocks persist, while script-local variables do not. Assign a JSON-compatible result to return data. Python stdout/stderr are capped at 64 Ki characters each; JSON results are limited to 4 MiB. Native Blender diagnostics do not enter the MCP stdout protocol.

The npm archive contains the Blender craft modules. bl_list_skills lists the modules in the installed package and their references/assets; bl_get_skill reads an entry or reference, and bl_get_skill_asset returns the local path of a bundled file. The original five bl_get_skill names remain valid. An MCP client can read this guidance directly without installing the modules as client-side skills; client-side installation is optional for hosts that support automatic skill activation. Existing installations do not gain new modules or tools until the npm package is updated and the MCP connection refreshed. Skill guidance does not execute Blender operations or prove a live connection.

Render a camera frame to PNG; files up to 4 MiB receive an inline preview. Cycles supports sample overrides. Save/render require overwrite: true for existing output files; opening a different project refuses unsaved changes unless explicitly discarded. Arbitrary Python is not sandboxed and can bypass these typed-tool guards. Automatic execution of Python embedded in opened .blend files is disabled.

Troubleshooting and limits

A timed-out job continues and keeps its job_id. Query bl_job_status before retrying; additional execution commands are rejected while it runs. No automatic retries or rollbacks occur. Status retains at most 128 jobs within the MCP process. If Blender crashes, the session fails and is not restarted automatically: inspect output files before reconnecting to a new empty session. Closing the MCP terminates its child process, including a running job; save needed changes first.

Use camera renders for visual evidence. No existing desktop scenes, preferences or installed add-ons are modified during startup. Multiple MCP connections have separate background scenes.

Verified on macOS arm64 with Blender 4.2.23 LTS: persistent scene, mesh/material/camera/light edits, keyframes, save/reopen guards and a Cycles PNG preview. Windows/Linux native Blender execution has not been verified locally.

The installed package includes UPSTREAM.md and LICENSE for provenance and licensing details.

Background Blender does not reliably mark direct Python edits as dirty. The MCP also tracks attempted mutations, including failed commands and arbitrary bl_execute calls, conservatively as unsaved until bl_save_project or an explicitly permitted bl_open_project succeeds. Read tools preserve this state.