Blender-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Blender-MCP Create a red cube with rounded edges"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
What it is · Why not the alternative · Tools · Quick start · Config · Docker · Architecture
Production-grade Blender automation over the Model Context Protocol. Pydantic-validated • Zero telemetry • Async-native • Pytest-covered • Plugin-extensible
Sibling project in the MCP-HUB collection.
🎯 What this is
blender-mcp connects Blender 3D to any MCP-compatible AI assistant
(Claude Desktop, Claude Code, Cursor, Continue, Cline, …). After a one-time
setup, you tell the assistant what you want, and it drives Blender for you —
creating objects, applying materials, lighting the scene, framing cameras,
rendering. The assistant takes the wheel; you watch it work.
flowchart LR
U["🧑 You<br/><i>natural language</i>"]:::user
AI["🤖 AI Client<br/>Claude · Cursor · Cline"]:::ai
B["🌉 Bridge Server<br/><i>this package</i>"]:::bridge
BL["🟠 Blender Addon<br/><i>main-thread exec</i>"]:::blender
U -->|prompt| AI
AI <-->|"MCP · stdio / http / sse"| B
B <-->|"TCP JSON · 127.0.0.1:9876"| BL
BL -.->|screenshot · render · scene data| B
B -.->|tool result| AI
AI -.->|answer| U
classDef user fill:#2d3436,stroke:#636e72,color:#fff
classDef ai fill:#0984e3,stroke:#74b9ff,color:#fff
classDef bridge fill:#6c5ce7,stroke:#a29bfe,color:#fff
classDef blender fill:#EA7600,stroke:#F5792A,color:#fffTwo halves:
Bridge server (this Python package, run via
uv) — speaks MCP to the AI client.Blender addon (
blender_addon/blender_mcp.py) — runs inside Blender, executes commands on the main thread.
Related MCP server: BlenderMCP
⚔️ Why use this instead of ahujasid/blender-mcp?
The blender-mcp project pioneered the space. We respect that. We're built
for a different audience: studios, technical artists, and pipeline engineers
who need verifiable, auditable, production-grade tooling.
Dimension | ✅ |
|
Telemetry | None. Zero phone-home. | Default-on Supabase telemetry |
Input validation | Pydantic v2 with | None — raw kwargs |
Async runtime | Native | Synchronous |
Tests | 207 passing, 90% coverage | None visible in repo |
CI | GitHub Actions on Python 3.10 / 3.11 / 3.12 | None |
Architecture | Modular package, ~8 files | Monolithic 1186-line |
Tool annotations | All 4 MCP hints on every tool | Mostly omitted |
Read-only mode |
| None |
Structured logging |
| Plain strings |
Protocol versioning |
| None |
Docker |
| None |
Hardcoded third-party keys | None — bring your own |
|
Asset integrations | Plugin packages (opt-in, separately versioned) | Baked into core |
If telemetry, validation, tests, audit-ability, or air-gapped deployment matter to you, this is the one to use.
🧰 Tools (v0.4.1)
15 core tools, all Pydantic-validated with full MCP annotations, plus opt-in plugin packs.
Tool | Purpose |
| Confirm Blender + addon reachable, returns versions and protocol |
| Scene name, frame range, render engine, object count |
| List objects, optional filter by type ( |
| Full per-object detail (transform, dimensions, materials, mesh/light/camera specifics) |
| Inline PNG of the active viewport |
Tool | Purpose |
| Cube / sphere / cylinder / cone / plane / torus / monkey |
| Set location / rotation / scale (any subset) |
| Remove by name (idempotent) |
| Principled BSDF: RGBA, metallic, roughness, optional emission |
| POINT / SUN / SPOT / AREA with per-type parameters |
| Location, aim target, focal length, set-active |
| Render a frame; returns metadata + inline PNG preview |
| Power-user escape hatch ( |
Tool | Purpose |
| Save the current |
| Open a |
🔌 Plugins — opt-in, separately installable
Each plugin is a pip package that registers additional tools via the entry-point system. Install only what you need. All require zero pre-configured secrets at server startup — keys are checked at call time, so the server always boots cleanly.
Tool | Purpose |
| Check plugin status and cache directory |
| List asset categories (hdris / textures / models) |
| Search PolyHaven's library |
| Download an asset to local cache |
| Download + apply texture to an object in Blender |
pip install blender-mcp-polyhavenTool | Purpose |
| Check plugin status and API key configuration |
| Text → 3D model via Rodin API |
| Image → 3D model (URL or local file) |
| Poll generation status with exponential backoff |
| Poll + download + import GLTF/FBX/OBJ/STL into Blender |
pip install blender-mcp-hyper3d
export HYPER3D_API_KEY="your-key" # https://hyper3d.aiTool | Purpose |
| Check plugin status and API key configuration |
| Search Sketchfab's 3D model library by keyword |
| Get full metadata for a model by UID |
| Download GLTF + import into Blender |
pip install blender-mcp-sketchfab
export SKETCHFAB_API_KEY="your-token" # https://sketchfab.com/settings#password🚀 Quick start
Prerequisites
Blender 3.0+ (3.6, 4.0, 4.2 LTS all tested)
Python 3.10+
uv package manager
# Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh
0 · Clone
git clone https://github.com/Aayushdubey101/Blender-MCP.git
cd Blender-MCP1 · Install dependencies
From the repo root:
uv sync2 · Install the Blender addon
Open Blender → Edit → Preferences → Add-ons → Install…
Pick
blender_addon/blender_mcp.pyTick the checkbox next to "Development: Blender MCP"
In the 3D viewport press N → MCP tab → ▶ Start MCP Bridge
You should see in Blender's system console:
[MCP Bridge] Listening on 127.0.0.1:98763 · Smoke-test the server
uv run blender-mcpIt will block on stdin — that's correct (MCP stdio transport). Press Ctrl-C. A clean run with no errors means you're good.
For a full interactive test, use the official inspector:
npx @modelcontextprotocol/inspector uv run blender-mcp4 · Wire it into your AI client
A ready-to-copy template is at .mcp.json.example.
Copy it, rename to .mcp.json (gitignored), and replace the path.
Replace <path-to-Blender-MCP> with the absolute path to this repo
(e.g. C:\Projects\Blender-MCP on Windows, /home/you/Blender-MCP on Linux/macOS).
%APPDATA%\Claude\claude_desktop_config.json (Windows) or
~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"blender": {
"command": "uv",
"args": [
"--directory",
"<path-to-Blender-MCP>",
"run",
"blender-mcp"
]
}
}
}claude mcp add blender -- uv --directory <path-to-Blender-MCP> run blender-mcpOr add manually to ~/.claude/settings.json:
{
"mcpServers": {
"blender": {
"command": "uv",
"args": ["--directory", "<path-to-Blender-MCP>", "run", "blender-mcp"]
}
}
}.cursor/mcp.json (or the equivalent config file for your client):
{
"mcpServers": {
"blender": {
"command": "uv",
"args": ["--directory", "<path-to-Blender-MCP>", "run", "blender-mcp"]
}
}
}Same shape everywhere — command: uv, args: [--directory <path>, run, blender-mcp]. See your client's MCP docs for the exact config file.
5 · Drive Blender with natural language
With Blender open, addon enabled, Start MCP Bridge running, and your AI client restarted — just ask. The assistant picks the right tools, validates inputs, and executes. You sit back.
You: Build a still-life scene. Put a glossy red sphere on a matte grey plane,
light it with a warm key light from the right and a cool rim from behind,
frame a 50mm camera looking down at 30°, then render at 720p with EEVEE....and here is the exact tool flow the assistant drives:
sequenceDiagram
autonumber
actor You
participant AI as 🤖 AI Client
participant Bridge as 🌉 Bridge
participant Blender as 🟠 Blender
You->>AI: "Glossy red sphere on grey plane, warm key + cool rim, 50mm cam, 720p"
AI->>Bridge: blender_ping
Bridge->>Blender: ping
Blender-->>Bridge: pong · v4.2 · protocol 1.0
loop build the scene
AI->>Bridge: create_primitive · set_material · add_light · set_camera
Bridge->>Blender: execute on main thread
Blender-->>Bridge: status success
end
AI->>Bridge: blender_render_image (EEVEE, 720p)
Bridge->>Blender: render frame
Blender-->>Bridge: PNG preview + metadata
Bridge-->>AI: inline image
AI-->>You: "Done — here's your render ✨"⚙️ Configuration
Every option is an environment variable. None are required; all have
sensible defaults. Copy .env.example to .env to customize.
Variable | Default | Purpose |
|
| Where the Blender addon is listening |
|
| Same — match the N-panel value |
|
|
|
|
|
|
|
|
|
Read-only mode (safe demos)
BLENDER_MCP_READ_ONLY=true uv run blender-mcpblender_create_primitive, blender_render_image, blender_execute_python, etc.
all return a structured "read-only mode" error. Inspection tools still work.
JSON logging (log infra)
BLENDER_MCP_LOG_FORMAT=json uv run blender-mcpEach line is a single JSON object — ship straight to Loki / Datadog / CloudWatch.
🐳 Docker
For headless / render-farm setups. The container talks to a Blender instance running on the host:
docker compose up --buildThe Blender addon must be running on the host (host.docker.internal:9876
inside the container). On Linux the compose file already maps
host.docker.internal to host-gateway.
📂 Project layout
Blender-MCP/
├── src/blender_mcp/
│ ├── server.py # MCP entry point; transport (stdio / http / sse)
│ ├── client.py # Async TCP client, per-call + persistent modes
│ ├── schemas.py # Pydantic v2 input models
│ ├── utils.py # format_error / format_success / read-only guard
│ ├── plugins/ # Plugin loader + BlenderMCPPlugin Protocol
│ ├── _log_formatter.py # JSON log formatter
│ └── tools/
│ ├── scene.py # inspection + file-management tools
│ ├── objects.py # destructive object/material/light/camera tools
│ ├── render.py # blender_render_image
│ └── code.py # blender_execute_python (escape hatch)
├── blender_addon/
│ └── blender_mcp.py # Install this in Blender
├── plugins/
│ ├── polyhaven/ # pip install blender-mcp-polyhaven
│ ├── hyper3d/ # pip install blender-mcp-hyper3d
│ └── sketchfab/ # pip install blender-mcp-sketchfab
├── tests/ # core test suite
├── docs/
│ └── ARCHITECTURE.md # Process model, threading, response shape, extensibility
├── examples/
│ └── direct_client_test.py # Drive the bridge without an MCP client
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml # uv / build configuration
├── .env.example
├── CHANGELOG.md
├── LICENSE
└── README.mdFor deeper internals see docs/ARCHITECTURE.md.
🧪 Development
uv sync --extra dev # install dev deps
uv run pytest # core tests, ~2s
uv run pytest --cov=src # with coverage
uv run ruff check src/ # lint
uv run ruff format src/ # format
uv run mypy src/ # type-check
# Run plugin tests
uv run pytest plugins/polyhaven/tests/ # 23 tests
uv run pytest plugins/hyper3d/tests/ # 44 tests
uv run pytest plugins/sketchfab/tests/ # 33 testsCI runs the same matrix on every push (Python 3.10 / 3.11 / 3.12).
🗺️ Roadmap
v0.3.0 ✅ — Plugin architecture, PolyHaven + Hyper3D + Sketchfab plugins, persistent connection, HTTP transport.
v0.4.x ✅ — SHA256 asset cache, headless
--backgroundBlender control, file management tools.v1.0.0 — Final polish, full comparison table green on every row.
🔧 Troubleshooting
Open Blender, Preferences → Add-ons, enable Blender MCP, then in the 3D viewport's N-panel → MCP tab → click ▶ Start MCP Bridge.
Change the port in the addon N-panel and set BLENDER_MCP_PORT to match.
Verify the absolute path in claude_desktop_config.json, then fully quit and
relaunch Claude Desktop (Cmd-Q / right-click tray icon → Quit).
Pass timeout_seconds=600 (or higher) on the blender_render_image call for
heavy Cycles renders. Default is 300s.
Re-install blender_addon/blender_mcp.py in Blender — your addon and
server are out of sync.
⭐ Star history
📜 License
MIT — see LICENSE.
Available Tools
15 toolsblender_add_lightA
Add a light source to the scene.
Supports POINT (omnidirectional), SUN (directional), SPOT (cone), and AREA (panel) lights.
Args: params: AddLightInput with light_type, optional name, location, energy, color, and type-specific settings (spot_size, size, etc.).
Returns: JSON with the light object name and properties.
Example: blender_add_light(light_type="POINT", location=(0, 0, 4), energy=2000)
Inputs: params (required). Returns: result
blender_create_primitiveA
Create a primitive mesh (cube, sphere, cylinder, etc.) in the scene.
Args: params: CreatePrimitiveInput with primitive_type, optional name, location (x, y, z), and size.
Returns: JSON describing the newly created object.
Example: blender_create_primitive(primitive_type="cube", name="MyCube", location=(0,0,1))
Inputs: params (required). Returns: result
blender_delete_objectADestructiveIdempotent
Delete an object from the scene by name.
DESTRUCTIVE: permanently removes the object. Idempotent: deleting a missing object returns success with a note.
Args:
params: DeleteObjectInput with the exact name of the object to delete.
Returns: JSON confirming the deletion.
Example: blender_delete_object(name="Cube")
Inputs: params (required). Returns: result
blender_execute_pythonADestructive
Execute arbitrary Python code inside Blender (escape hatch for advanced ops).
The code runs with bpy already imported. To return data, assign it to
a variable named result. Use this only when no dedicated tool fits.
DESTRUCTIVE: arbitrary code can modify or delete anything in the scene.
Args:
params: ExecutePythonInput with the code string to execute (max 20,000 chars).
Returns:
JSON with the value of result (if set) or a success confirmation.
Example: code = "result = [obj.name for obj in bpy.data.objects if obj.type == 'MESH']"
Inputs: params (required). Returns: result
blender_get_object_infoARead-onlyIdempotent
Get detailed information about a specific object by name.
Returns transform, dimensions, material slots, and type-specific data (mesh stats for MESH, light settings for LIGHT, focal length for CAMERA).
Args:
params: GetObjectInfoInput with the object name and response_format.
Returns: Markdown summary or JSON with full object properties.
Example: blender_get_object_info(name="Cube")
Inputs: params (required). Returns: result
blender_get_scene_infoARead-onlyIdempotent
Get an overview of the current Blender scene.
Returns scene name, frame range, render engine, and total object count.
Args: params: GetSceneInfoInput with response_format ('markdown' or 'json').
Returns: Markdown summary or JSON object describing the scene.
Example: blender_get_scene_info(response_format="json")
Inputs: params (required). Returns: result
blender_get_viewport_screenshotARead-onlyIdempotent
Capture a screenshot of the current Blender 3D viewport.
Renders using OpenGL and returns the image inline. Great for inspecting the current state of the scene visually.
Args:
params: ViewportScreenshotInput with max_size (default 800px).
Returns: An inline PNG image of the viewport, or an error string if capture fails.
Example: blender_get_viewport_screenshot(max_size=1024)
Inputs: params (required).
blender_list_objectsARead-onlyIdempotent
List objects in the current Blender scene, optionally filtered by type.
Args:
params: ListObjectsInput with optional object_type filter (e.g. 'MESH')
and response_format.
Returns: Markdown table or JSON list of objects with name, type, and location.
Example: blender_list_objects(object_type="MESH", response_format="json")
Inputs: params (required). Returns: result
blender_open_fileADestructive
Open a .blend file in Blender, replacing the current scene.
WARNING: Unsaved changes to the current scene will be lost.
Args:
params: OpenFileInput with filepath (absolute path to .blend file).
Returns: JSON confirming the file that was opened.
Example: blender_open_file(filepath="/home/user/projects/scene.blend")
Inputs: params (required). Returns: result
blender_pingARead-onlyIdempotent
Check whether Blender is running and the bridge addon is reachable.
Use this as the first step before any other tool to confirm the integration is live.
Returns:
JSON with status and a message indicating reachability.
Example: blender_ping() → {"status": "success", "result": {"reachable": true}}
Inputs: no named parameters. Returns: result
blender_render_imageA
Render a frame using Blender's render engine and return the result inline.
Blocks until the render is complete. For fast previews use EEVEE; for photorealistic output use CYCLES (much slower — increase timeout_seconds).
Returns both a JSON metadata block and an inline image preview. If output_path is given the full-resolution render is also saved to disk.
Args: params: RenderImageInput with optional frame, output_path, engine override, Cycles sample override, preview size, and timeout.
Returns: List of [metadata JSON string, inline PNG preview Image].
Example: blender_render_image(engine="BLENDER_EEVEE", frame=1, max_preview_size=512) blender_render_image(engine="CYCLES", samples=64, timeout_seconds=600)
Inputs: params (required).
blender_save_fileAIdempotent
Save the current Blender scene to a .blend file.
Args:
params: SaveFileInput with optional filepath. Uses the currently
open file path if omitted.
Returns: JSON with the path the file was saved to.
Example: blender_save_file(filepath="/tmp/my_scene.blend") blender_save_file() # saves to current file path
Inputs: params (required). Returns: result
blender_set_cameraAIdempotent
Configure a camera's position, aim target, and focal length.
Uses the active scene camera if no name is given. Creates a new camera if the scene has none. Optionally points the camera at a 3D target point.
Args: params: SetCameraInput with optional name, location, target (point to aim at), lens (focal length in mm), and set_active flag.
Returns: JSON with the camera name, location, rotation, and lens.
Example: blender_set_camera(location=(5, -5, 3), target=(0, 0, 0), lens=50)
Inputs: params (required). Returns: result
blender_set_materialAIdempotent
Apply a PBR material to an object using Principled BSDF.
Creates or updates a material with the given base color, metallic, roughness, and optional emission. Assigns it to the first material slot of the object.
Args: params: SetMaterialInput with object_name, color (RGBA), metallic, roughness, optional material_name, and optional emission.
Returns: JSON with the material name and applied properties.
Example: blender_set_material(object_name="Cube", color=(0.2, 0.4, 0.8, 1.0), metallic=0.9)
Inputs: params (required). Returns: result
blender_transform_objectAIdempotent
Set location, rotation, and/or scale of an existing object.
Any field left as None is left unchanged. This is idempotent — calling
with the same values is a no-op.
Args:
params: TransformObjectInput with the target object name and any
combination of location, rotation_euler, and scale.
Returns: JSON with the updated transform values.
Example: blender_transform_object(name="Cube", location=(1,0,0), scale=(2,2,2))
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool has a clearly distinct purpose: scene overview, object listing, detailed object info, file operations, viewport capture, primitive creation, transformation, deletion, material application, light addition, camera setup, and rendering. The Python escape hatch is explicitly marked as a fallback, avoiding confusion.
All tools follow a strict blender_verb_noun pattern (e.g., get_scene_info, create_primitive, set_material). This consistent convention makes the tool set predictable and easy to navigate.
With 15 tools, the set is well-scoped for a Blender automation workflow. Each tool covers a necessary operation from scene inspection to rendering, and the count remains within the ideal 3-15 range without bloat.
The tool set covers the full CRUD lifecycle for objects, plus materials, lights, camera, and rendering. Advanced Blender features like modifiers, animation, and mesh editing are not directly exposed, but the blender_execute_python escape hatch covers these gaps, so agents won't hit dead ends.
Maintenance
Related MCP Connectors
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Blender-as-a-service for agents: search 3D assets, run Blender Python, or brief the studio agent.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseBqualityDmaintenanceConnects Blender to Claude AI through the Model Context Protocol, enabling AI-assisted 3D modeling, scene creation, and manipulation through natural language commands.172MIT
- AlicenseBqualityCmaintenanceConnects Blender to AI through the Model Context Protocol to enable prompt-assisted 3D modeling and scene manipulation. It supports object creation, material control, and arbitrary Python code execution directly within the Blender environment.22MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to control Blender 3D modeling and rendering through natural language commands via the Model Context Protocol.MIT
- AlicenseNot gradedqualityDmaintenanceConnects Blender to AI assistants through the Model Context Protocol, enabling direct AI control of 3D modeling, scene creation, and manipulation via natural language.MIT