three.ws Blender — Claude Code MCP server: render and convert 3D
Points your agent at the Blender already on your machine, headless: look inside a 3D file, switch formats, render a preview and run bpy scripts.
claude mcp add --env BLENDER_PATH=<BLENDER_PATH> --env BLENDER_MCP_TIMEOUT_MS=<BLENDER_MCP_TIMEOUT_MS> --env BLENDER_MCP_WORKDIR=<BLENDER_MCP_WORKDIR> --env BLENDER_MCP_ALLOW_PYTHON=<BLENDER_MCP_ALLOW_PYTHON> --env BLENDER_MCP_INLINE_IMAGE_BYTES=<BLENDER_MCP_INLINE_IMAGE_BYTES> --transport stdio blender-mcp -- npx -y @three-ws/blender-mcpWhat three.ws Blender does
Every call starts real Blender in background mode (blender -b) and talks to the assistant over stdio. No window, no add-on inside Blender, so it fits a server, CI or a container without a display. Each tool drives the copy of Blender installed on the host.
Seven tools cover the routine work. blender_scene_info reports objects, triangles, materials, textures, bones and actions. blender_convert picks import and export formats from the file extensions. blender_optimize trims triangles, shrinks textures and prints a before/after report. blender_render returns a PNG inline and adds a camera and lighting when the scene lacks them. blender_run_python executes a bpy script, blender_forge_import builds a model from a prompt or a reference image, and blender_info lists what your build supports. Meshopt- and Draco-compressed glTF gets decoded in process, so no extra binary is needed.
Node.js 20+ and Blender 3.0 or newer are required. Set BLENDER_PATH when the executable is not on PATH; otherwise the server cannot find Blender. Available formats follow the local build, and blender_info reports the real list. Large renders run into the timeout setting.
What it helps with
- inspect an FBX or GLB before touching it
- turn a client FBX into a web-ready GLB at the right scale
- cut triangles and texture size for a delivery budget
- get a model preview straight into the agent reply
- run a
bpyscript on a scene and export the result
Example prompts for the agent
- Describe
~/assets/character.fbxfor me: meshes, triangle count, bones, actions. - Convert
character.fbxtocharacter.glbat scale 0.01, then render four views. - Generate a weathered brass diving helmet and save it as
helmet.blend.
How to install three.ws Blender
Platform CLI
claude mcp add --env BLENDER_PATH=<BLENDER_PATH> --env BLENDER_MCP_TIMEOUT_MS=<BLENDER_MCP_TIMEOUT_MS> --env BLENDER_MCP_WORKDIR=<BLENDER_MCP_WORKDIR> --env BLENDER_MCP_ALLOW_PYTHON=<BLENDER_MCP_ALLOW_PYTHON> --env BLENDER_MCP_INLINE_IMAGE_BYTES=<BLENDER_MCP_INLINE_IMAGE_BYTES> --transport stdio blender-mcp -- npx -y @three-ws/blender-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
codex mcp add blender-mcp --env BLENDER_PATH=<BLENDER_PATH> --env BLENDER_MCP_TIMEOUT_MS=<BLENDER_MCP_TIMEOUT_MS> --env BLENDER_MCP_WORKDIR=<BLENDER_MCP_WORKDIR> --env BLENDER_MCP_ALLOW_PYTHON=<BLENDER_MCP_ALLOW_PYTHON> --env BLENDER_MCP_INLINE_IMAGE_BYTES=<BLENDER_MCP_INLINE_IMAGE_BYTES> -- npx -y @three-ws/blender-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"mcpServers": {
"blender-mcp": {
"command": "npx",
"args": [
"-y",
"@three-ws/blender-mcp"
],
"env": {
"BLENDER_PATH": "<BLENDER_PATH>",
"BLENDER_MCP_TIMEOUT_MS": "<BLENDER_MCP_TIMEOUT_MS>",
"BLENDER_MCP_WORKDIR": "<BLENDER_MCP_WORKDIR>",
"BLENDER_MCP_ALLOW_PYTHON": "<BLENDER_MCP_ALLOW_PYTHON>",
"BLENDER_MCP_INLINE_IMAGE_BYTES": "<BLENDER_MCP_INLINE_IMAGE_BYTES>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"servers": {
"blender-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/blender-mcp"
],
"env": {
"BLENDER_PATH": "<BLENDER_PATH>",
"BLENDER_MCP_TIMEOUT_MS": "<BLENDER_MCP_TIMEOUT_MS>",
"BLENDER_MCP_WORKDIR": "<BLENDER_MCP_WORKDIR>",
"BLENDER_MCP_ALLOW_PYTHON": "<BLENDER_MCP_ALLOW_PYTHON>",
"BLENDER_MCP_INLINE_IMAGE_BYTES": "<BLENDER_MCP_INLINE_IMAGE_BYTES>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
gemini mcp add -e BLENDER_PATH=<BLENDER_PATH> -e BLENDER_MCP_TIMEOUT_MS=<BLENDER_MCP_TIMEOUT_MS> -e BLENDER_MCP_WORKDIR=<BLENDER_MCP_WORKDIR> -e BLENDER_MCP_ALLOW_PYTHON=<BLENDER_MCP_ALLOW_PYTHON> -e BLENDER_MCP_INLINE_IMAGE_BYTES=<BLENDER_MCP_INLINE_IMAGE_BYTES> blender-mcp npx -y @three-ws/blender-mcpReplace <…> with your own values. 5 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about three.ws Blender
How do I install three.ws Blender in Claude Code?
Run claude mcp add blender-mcp -e THREE_WS_FORGE_PROVIDER_KEY=<THREE_WS_FORGE_PROVIDER_KEY> -- npx -y @three-ws/blender-mcp. For a Blender outside PATH, the second form passes BLENDER_PATH, BLENDER_MCP_TIMEOUT_MS, BLENDER_MCP_WORKDIR, BLENDER_MCP_ALLOW_PYTHON and BLENDER_MCP_INLINE_IMAGE_BYTES via --env with the stdio transport.
What does three.ws Blender do?
It hands an AI assistant your local Blender: scene inspection, conversion across GLB, glTF, FBX, OBJ, STL, PLY, Collada, Alembic, USD and .blend, optimisation, inline PNG renders and bpy scripts.
Do compressed glTF files work?
Yes. Assets using meshopt or Draco are unpacked inside the process before Blender opens them. Your original file stays untouched, and the response names what was decoded.
