@three-ws/blender-mcp

Give any AI agent the Blender on your machine. Headless, no GUI, no add-on to install.

A Model Context Protocol server that hands an AI assistant a real Blender over stdio. Inspect a 3D file, convert between GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend, render an auto-framed and auto-lit preview that comes back inline so the assistant can see it, run a bpy script against a scene, and generate a model from a text prompt on the free three.ws Forge lane.

Blender runs in background mode (blender -b), one process per call. That means it works on a server, in CI, and inside a container with no display, no GUI session to keep alive, and no add-on to install into Blender first. Everything is real: each tool drives the Blender installed on the machine, and blender_forge_import calls the live public three.ws generation pipeline.

#Requirements

• Node.js 20+
• Blender 3.0 or newer, installed locally. Download it, or install it from your package manager. If it is not on PATH, set BLENDER_PATH to the executable (/Applications/Blender.app/Contents/MacOS/Blender on macOS).

Call blender_info first if anything misbehaves: it reports the exact executable, version, render engines, and file formats this build supports.

#Install

npm install @three-ws/blender-mcp

Or run it with npx (no install):

npx -y @three-ws/blender-mcp

#Claude Code

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

#Claude Desktop / Cursor

Paste this into your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
	"mcpServers": {
		"blender": {
			"command": "npx",
			"args": ["-y", "@three-ws/blender-mcp"]
		}
	}
}

Add "env": { "BLENDER_PATH": "/path/to/blender" } if Blender is not on PATH.

#Tools

#Examples

Describe a file before touching it:

> What is in ~/assets/character.fbx?

blender_scene_info { "input": "~/assets/character.fbx" }
→ 4 meshes, 41,208 triangles, 1 armature (67 bones), 3 actions, bounds 1.78m tall

Make a model shippable and see what it cost:

blender_optimize { "input": "character.glb", "output": "character-web.glb", "max_triangles": 30000, "max_texture_px": 1024 }
→ 4.1 MB to 780 KB (81% saved): 96,412 to 30,000 triangles, textures 2048 to 1024, meshopt compressed

Look at it from four sides at once:

blender_render { "input": "character-web.glb", "views": 4 }

Convert a client's FBX into a web-ready GLB, in metres:

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

See what you just made:

blender_render { "input": "character.glb", "output": "preview.png", "samples": 64 }

Halve the triangle count and export in one call:

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'])}"
}

Generate an asset and open it as a .blend:

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

Or reconstruct one from a reference image:

blender_forge_import { "image": "./reference.png", "prompt": "a brass diving helmet", "output": "helmet.glb" }

#Compressed glTF

Meshopt- and Draco-compressed assets are decoded automatically before Blender opens them, in process, with no external binary to install.

This is not a nicety. Blender's glTF importer has no decoder for EXT_meshopt_compression, which is what gltfpack emits and what most three.ws avatars are delivered as; handed one it fails outright 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 do not. Every tool that takes an input goes through the same decode, and the response names what was decoded in decoded_compression. Your file is never modified: the decoded copy lives in the job's scratch directory and is deleted with it.

#How a call works

Every tool call spawns blender -b --factory-startup --python src/py/runner.py -- <job.json> <result.json> and exits. Three consequences worth knowing:

• --factory-startup keeps your saved preferences and third-party add-ons out of the result, so a 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, and picking a payload out of that stream is guesswork. A missing result file therefore means 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 nothing stays resident between calls.

Failures come back as structured tool errors (input_not_found, format_unsupported, engine_unavailable, timeout, blender_not_found, blender_unusable, blender_crashed), each with a message that says what to do about it. blender_not_found means no candidate exists; blender_unusable means one exists but would not run, and carries the per-candidate diagnostics, because on a loaded machine a failed probe is transient and telling you to install software you already have is the wrong answer.

#Environment variables

#Security

blender_run_python executes caller-supplied Python inside Blender with the permissions of this server: it can read and write the local filesystem. That is the point of the tool, and it is annotated destructiveHint: true so a client can prompt before running it. For unattended or shared deployments, set BLENDER_MCP_ALLOW_PYTHON=0 and the tool is never advertised.

Everything else stays local. Only blender_forge_import reaches the network, and only to the three.ws deployment named by THREE_WS_BASE.

#Development

node src/index.js                        # run the server over stdio
npm test                                 # offline invariants + real-Blender integration
npm run inspect                          # open the MCP Inspector against it

test/registration.test.mjs runs offline and passes with no Blender installed. test/blender-session.test.mjs drives the server through a real MCP stdio session against the local Blender, building its fixture with Blender itself; it skips cleanly when no Blender is present.

#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 package is the agent-facing one.
• @three-ws/scene-mcp composes whole 3D worlds from a sentence.
• three.ws is the platform behind the Forge pipeline.

#License

Apache-2.0