blender-mcp-ultra
The most complete MCP server for Blender โ control Blender with natural language from any AI agent: Claude Code, Claude Desktop, Cursor, opencode, Windsurf, Antigravity, LM Studio, Ollama and any Model Context Protocol (MCP) client.
239 tools ยท Windows / macOS / Linux ยท headless-ready ยท production-grade security

Scene above: 100% created and rendered by an AI agent through this MCP server โ no manual modeling.
Gallery โ what agents build with it
Every image above was generated end-to-end through MCP tools โ scene setup, materials, lighting, camera framing, simulation and final Cycles render.
What is it?
blender-mcp-ultra connects Blender (the free open-source 3D suite) to LLM agents through the Model Context Protocol. Ask your AI assistant to model, texture, light, animate, simulate and render 3D scenes โ it executes through 248 typed tools instead of fragile screenshot-guessing.
You: "Create a wooden table with a coffee mug on it and render it in Cycles"
Claude: โ object.create, mesh ops, material PBR wood, light.three_point,
camera.set_framing, render.render โ escena.png
Highlights
- ๐งฐ 248 MCP tools (7 base + 241 registry, incl. built-in workflow guidance) โ modeling, materials, shader nodes, geometry nodes, lighting, cameras, animation, physics, compositor, UV, rigging, 3D printing, export (FBX/OBJ/glTF/STL), batch, VLM visual feedback, multi-agent collab, scene planner
- ๐ฅ๏ธ Any MCP client โ stdio (Claude Code/Desktop, Cursor, opencode, VS Code, Windsurf), SSE/HTTP (Antigravity, remote), REST
- ๐ง VLM feedback loop โ the agent sees its renders (EEVEE headless capture) and iterates
- ๐ Security-first โ AST code blocklist validated in gateway and addon, mandatory auth token (auto-generated), localhost-only binding, rate limiting, 0 secrets in history (gitleaks)
- ๐ค Multi-provider โ OpenAI, Anthropic, Google, DeepSeek, Ollama (local)
- ๐ฆ Asset integrations โ PolyHaven, Sketchfab, AmbientCG, Hyper3D
- ๐ Headless CI โ real E2E tests against Blender in GitHub Actions (Linux + Windows + macOS)
- ๐งช 479 tests passed ยท ruff ยท bandit ยท pip-audit clean
Quick Start
1. Install the Blender addon
Download blender_mcp_ultra.zip โ Blender โ Edit > Preferences > Add-ons > Installโฆ โ enable blender-mcp-ultra โ click Connect in the N-panel.
Or install from this repo (Blender 4.2+/5.x):
git clone https://github.com/carlosh7/blender-mcp.git
cd blender-mcp
pip install -e .
2. Connect your AI client
Install the gateway (provides the blender-mcp-server command). Startup order doesn't matter: all tools register even if Blender is closed and work as soon as you open it.
pip install blender-mcp-ultra
claude mcp add blender -- blender-mcp-server
# o, desde un checkout del repo:
claude mcp add blender -- python /ruta/a/blender-mcp/mcp_server.py
More: docs/clients/claude-code.md
{
"mcpServers": {
"blender": {
"command": "blender-mcp-server"
}
}
}
More: docs/clients/claude-desktop.md ยท cursor.md ยท vscode.md
python mcp_server.py # el addon auto-escribe ~/.config/opencode/mcp.json
More: docs/clients/opencode.md
python mcp_server.py --sse # SSE en :9879 (MCP_SSE_HOST para exponer)
# REST local: http://localhost:9877 (mismo token que el socket: ~/.config/blender-mcp/socket_token)
# Docker:
docker build -t blender-mcp-gateway . && docker run -p 9879:9879 blender-mcp-gateway
More: docs/clients/antigravity.md ยท docs/remote.md
3. Ask your agent
"Modela una silla de madera con biselado y material PBR, ilumina en 3 puntos y renderiza"
Tools (248)
Full reference generated from the live registry: docs_scene tool ยท skills/recetas en docs/skills/.
Security
Run trusted agents only โ executing Blender Python on the agent's behalf is the product.
Architecture
AI Agent (Claude/Cursor/โฆ) โโMCP stdio/SSEโโโถ mcp_server.py (gateway, 248 tools)
โ socket :9876 (localhost + token)
โผ
Blender + addon blender-mcp-ultra
(handlers, validators, PBR, physicsโฆ)
mcp_ultra/ # hexagonal: core / adapters / infrastructure / presentation / tools
addon/ # Blender addon: socket server, handlers, PBR factory, anti-blockout
docs/ # client guides, skills recipes, tutorials
tests/ # 479 tests (unit + integration + e2e headless)
Testing
pytest tests/unit -q # sin Blender
pytest -q # completo (requiere Blender con el addon conectado)
CI ejecuta la suite completa contra Blender headless en cada push (Linux, Windows, macOS).
FAQ
Does it work with ChatGPT / Gemini? Any client that speaks MCP works. For providers without MCP support, the bundled REST API (:9877) accepts plain HTTP.
Does Blender need to be open? Yes for interactive work (it drives the real Blender). CI/headless render jobs run with blender -b โ see docs/skills/headless_ci.md.
Is it safe? The agent can execute Blender Python โ that's the product. Execution is sandboxed, validated by AST, rate-limited and bound to localhost with token auth. Run trusted agents only.
Blender versions? 4.2+ (LTS) and 5.x. Python 3.10+ for the gateway.
Contributing
PRs welcome โ read CONTRIBUTING.md. Docs: GUIDE.md ยท ARCHITECTURE.md ยท CHANGELOG.md
License
MIT โ see LICENSE.


