@three-ws/blender-mcp

@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

Tool	What it does
blender_info	Reports the Blender being driven: path, version, bundled Python, usable render engines, and the import/export formats this build actually supports. Read-only.
blender_scene_info	Opens a 3D file and describes it: objects with types, parents, dimensions and modifiers; evaluated triangle and vertex counts; materials; a texture inventory with each image's resolution and byte size; armature bone names; animation actions with frame ranges; world-space bounds. Read-only.
blender_convert	Imports one format and exports another, chosen by the file extensions. Applies modifiers by default and can bake in a uniform unit scale. The exact format list depends on the build (some Linux packages ship without USD, Collada, or Alembic), and blender_info reports what yours actually has.
blender_optimize	The delivery pass in one call: decimate to a triangle budget, scale oversized textures, purge unreferenced datablocks, and compress the mesh streams with meshopt or Draco. Reports before and after triangles, texture bytes and file size.
blender_render	Renders a still PNG and returns it inline, so the assistant can actually see the model in one call even with no filesystem access. Ask for several views and it orbits the model, every angle in the same launch. If the file has no camera, one is created and framed to the model's bounding sphere; if it has no light, a key light and a lit world are added. A scene that already has its own camera and lighting renders as authored.
blender_run_python	Runs a bpy script against a scene, optionally opening a file first and exporting the result afterwards. The escape hatch for anything the other tools do not cover.
blender_forge_import	Generates a model from a text prompt or a reference image on the public three.ws Forge pipeline and brings it into Blender, converting on the way in if the output asks for another format. The default lane is free.

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

Variable	Default	Purpose
BLENDER_PATH	discovered on PATH and at the platform's standard install locations	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 when a tool is called without an explicit output path.
BLENDER_MCP_ALLOW_PYTHON	1	Set to 0 to withdraw blender_run_python from the advertised tool list entirely.
BLENDER_MCP_MAX_CONCURRENCY	2	Blender processes allowed at once. Further calls queue rather than compete for memory.
BLENDER_MCP_INLINE_IMAGE_PX	768	Longest edge of the render copy returned inline. The full-resolution PNG always goes to disk.
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 text-to-3D generation.
THREE_WS_FORGE_PROVIDER_KEY	unset	Meshy/Tripo key for the bring-your-own-key geometry lane. The default image lane is free and needs no key.

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