MCP for Blender
Connect Blender to any LLM
formerly blender-mcp — the PyPI package is now mcp-for-blender.
Existing setups keep working; no config change is required. Read more
Disclaimer: This is a third-party integration and not made by Blender
Prompt-assisted 3D modeling, scene creation, and manipulation — driven by AI.
Website · Full Tutorial · Discord · Sponsor · Buy me a coffee · Feedback
Supporters
CodeRabbit
Kevin Guanche Darias
Guillermo Rauch
All supporters: Support this project
Table of Contents
Features
| |
|---|
| Two-way communication | Connect Claude AI to Blender through a socket-based server |
| Object manipulation | Create, modify, and delete 3D objects in Blender |
| Material control | Apply and modify materials and colors |
| Scene inspection | Get detailed information about the current Blender scene |
| Code execution | Run arbitrary Python code in Blender from Claude |
| Asset & model generation | Poly Haven assets, Sketchfab models, Poly Pizza low-poly models, and AI-generated 3D models via Hyper3D Rodin and Hunyuan3D |
Components
The system consists of two main components:
- Blender Addon (
addon.py) — a Blender addon that creates a socket server within Blender to receive and execute commands
- MCP Server (
src/blender_mcp/server.py) — a Python server that implements the Model Context Protocol and connects to the Blender addon
Run with Docker
You can run the MCP server in a container instead of installing it. Blender itself still runs on your machine — the container only hosts the MCP server, which connects out to the Blender addon.
Build the image from the repo root:
docker build -t mcp-for-blender .
Then point your MCP client at it (the -i flag is required — the server talks to the client over stdin/stdout):
{
"mcpServers": {
"blender": {
"command": "docker",
"args": ["run", "-i", "--rm", "mcp-for-blender"]
}
}
}
The image defaults to BLENDER_HOST=host.docker.internal, which reaches the host's Blender out of the box with Docker Desktop on macOS and Windows.
On Linux, host.docker.internal doesn't exist and the addon only listens on localhost, so use host networking instead:
{
"mcpServers": {
"blender": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "mcp-for-blender"]
}
}
}
To enable safe mode in the container, add "-e", "BLENDER_MCP_SAFE_MODE=1" to args.
Environment Variables
The following environment variables can be used to configure the Blender connection:
| Variable | Default | Description |
|---|
BLENDER_HOST | localhost | Host address for Blender socket server |
BLENDER_PORT | 9876 | Port number for Blender socket server |
BLENDER_MCP_SAFE_MODE | off | Set to 1 to validate scripts before they run in Blender (see below) |
Example:
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
You can also pass the connection as CLI flags, which take precedence over the
environment variables. This is handy for running several Blender instances side
by side, since each MCP client entry can point at a different port with plain
arguments instead of env vars:
uvx mcp-for-blender --port 9877
In an MCP client config that means a second entry differing only in args:
{
"mcpServers": {
"blender": { "command": "uvx", "args": ["mcp-for-blender"] },
"blender-b": { "command": "uvx", "args": ["mcp-for-blender", "--port", "9877"] }
}
}
Each instance needs its own port set in the Blender addon panel to match.
Note: the addon's socket server has no authentication or encryption, so
anyone who can reach that port can run Python inside Blender. Keep it on
localhost unless you are on a trusted network, and prefer an SSH tunnel over
pointing --host/BLENDER_HOST at a remote machine directly.
Safe mode
By default, the AI can run any Python code in Blender. Set BLENDER_MCP_SAFE_MODE=1 to check every script before it runs and block risky code — things like reading or writing files directly, running other programs, accessing the network, or installing code that keeps running after the script ends. Normal Blender work (modeling, materials, rendering, saving, import/export) still works. Blocked scripts are sent back to the AI with the reason, so it can try again with a corrected version.
Upgrading (existing users)
For newcomers, go straight to Quickstart. For existing users, see below.
1. Update the addon file by running:
uvx mcp-for-blender install-addon
uvx mcp-for-blender addon-paths # optional: list detected Blender addons folders
2. In Blender: Preferences → Add-ons → disable and re-enable Interface: MCP for Blender (or restart Blender), then click Start MCP Server again.
3. Delete the MCP server from Claude and add it back again if the server package itself needs a refresh.
Note: the MCP server never modifies your Blender addon files on its own. When it starts, it checks whether the installed addon is behind the bundled copy and logs how to update; install-addon is what actually writes, and it keeps a .bak of the file it replaces. Trajectory capture still works on older loaded addons via an execute_code fallback.
Usage
Starting the Connection
- In Blender, go to the 3D View sidebar (press N if not visible)
- Find the MCP for Blender tab
- Turn on the checkboxes you'd like to use (see more under Capabilities below)
- Click Connect to Claude
- Make sure the MCP server is running in your terminal
Using with Claude
Once the config file has been set on Claude, and the addon is running on Blender, you will see a hammer icon with tools for MCP for Blender.
Capabilities
- Get scene and object information
- Create, delete and modify shapes
- Apply or create materials for objects
- Execute any Python code in Blender
- Export the scene, the selection or named objects to GLB/FBX for other applications (
export_scene)
- Look up node schemas and the bpy API reference instead of guessing socket order or enum names
- Search and download free CC0 HDRIs, textures and models from Poly Haven
- Search and download models from Sketchfab
- Search and download low-poly models from Poly Pizza
- AI generated 3D models through Hyper3D Rodin and Hunyuan3D
Hunyuan3D on Tencent Cloud (Official API mode)
Which Tencent Cloud service the addon must call depends on where your account lives:
| Account | Service the addon calls | Region | Sidebar toggle |
|---|
| Mainland (cloud.tencent.com) | AI3D 3.0 (ai3d, version 2025-05-13) | ap-guangzhou | leave International (Pro) account off (default) |
| International (tencentcloud.com), Hunyuan-to-3D (Professional) | hunyuan, version 2023-09-01, PBR enabled | ap-singapore | tick International (Pro) account |
International credentials sent to the mainland endpoint fail with AuthFailure.SignatureFailure or
ResourceUnavailable, so tick the toggle when your SecretId/SecretKey come from tencentcloud.com.
The toggle sits under Tencent Hunyuan 3D → Official API in the sidebar.
Poly Haven
Poly Haven publishes around 2,400 HDRIs, textures and models,
all CC0 and free, funded by donations rather than by selling the assets. There is no API
key, no account and no rate limit worth worrying about.
In the 3D View sidebar, tick Poly Haven. That is the whole setup.
Worked example:
"Light the scene with an overcast afternoon HDRI and put a rusty metal texture on the wall"
Claude calls search_polyhaven_assets(query="overcast afternoon", asset_type="hdris"),
which understands the intent rather than matching keywords - "couch" finds sofas, and it
works in any language. It can then check the thumbnail with
get_polyhaven_asset_preview(asset_id="...") before spending the bandwidth, and import
with download_polyhaven_asset(...).
get_polyhaven_categories(asset_type="textures") returns the category tree and every
attribute that type can be filtered on, each with the values it accepts - weather and time
of day for HDRIs, surface use and condition for textures, material and whether a model is
rigged or ships level-of-detail variants. Pass a category path or those attributes to
search_polyhaven_assets; matching on a category is inclusive, so a parent selects
everything nested beneath it.
Models are imported from the .blend, which is the file the artist authored - the glTF,
FBX and USD versions are generated from it and lose material detail. Textures build a
Principled material from the maps that drive it, and skip the repackings and alternate
conventions that nothing reads. HDRIs are packed into the file, so the lighting survives
being saved and reopened somewhere else, and arrive in a new world rather than overwriting
one you built.
Licence and attribution: every Poly Haven asset is CC0. You never have to credit
anyone, for anything, commercial or not. Their
API terms do ask that
software built on the live API makes clear where the assets come from, so the search and
import responses name the source and link the asset's page. On import, polyhaven_id,
polyhaven_url, polyhaven_authors, polyhaven_resolution and polyhaven_licence are
written onto the imported objects, materials, images and world as custom properties, so
whoever opens the .blend later can still find the asset and the artist who made it.
Poly Pizza
Poly Pizza hosts roughly 10,600 free low-poly models, including the
rescued Google Poly archive. It is the best source for stylised game assets: every model is
a single self-contained .glb, and the geometry is far lighter than Sketchfab's.
- Get a free API key at poly.pizza/settings/api
- In the 3D View sidebar, tick Use assets from Poly Pizza
- Paste the key into the API Key field that appears (or store it permanently under
Edit → Preferences → Add-ons → MCP for Blender)
Worked example:
"Search Poly Pizza for a low-poly chair under a CC0 licence and import one at 1 metre tall"
Claude calls search_polypizza_models(query="chair", licence="CC0"), which returns each
match with its licence and triangle count, then
download_polypizza_model(model_id="...", normalize_size=True, target_size=1.0).
You can also filter by category ("Animals", "Furniture & Decor", "Transport",
"Nature", "Buildings", "People & Characters", "Food & Drink", "Weapons",
"Clutter", "Objects", "Scenes & Levels", "Other") or ask for animated models only.
Attribution: about 69% of the Poly Pizza catalogue is CC-BY, which requires you to
credit the creator wherever the model appears. On import, the ready-formatted credit line
is written onto each imported root object as the custom property polypizza_attribution
(alongside polypizza_id and polypizza_licence), so it is saved into your .blend and
survives the session. Filter with licence="CC0" if you would rather use models that need
no credit.
Example Commands
Here are some examples of what you can ask Claude to do:
| Prompt | Demo |
|---|
| "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" | Watch |
| "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" | Watch |
| Give a reference image, and create a Blender scene out of it | Watch |
| "Get information about the current scene, and make a threejs sketch from it" | Watch |
| "Generate a 3D model of a garden gnome through Hyper3D" | |
| "Fill this room with low-poly furniture from Poly Pizza" | |
| "Make this car red and metallic" | |
| "Create a sphere and place it above the cube" | |
| "Make the lighting like a studio" | |
|
Persistent API Credentials
MCP for Blender supports persistent credentials via Blender Add-on Preferences:
Edit → Preferences → Add-ons → MCP for Blender
You can store these values there so they survive Blender restarts:
- Sketchfab API Key
- Poly Pizza API Key
- Hyper3D API Key
- Hunyuan3D SecretId / SecretKey
- Hunyuan3D API URL
For headless setups or CI, credentials can also be injected by environment variables:
| Variable |
|---|
BLENDERMCP_SKETCHFAB_API_KEY |
BLENDERMCP_POLYPIZZA_API_KEY |
BLENDERMCP_HYPER3D_API_KEY |
BLENDERMCP_HUNYUAN3D_SECRET_ID |
BLENDERMCP_HUNYUAN3D_SECRET_KEY |
BLENDERMCP_HUNYUAN3D_API_URL |
Troubleshooting
| Problem | Fix |
|---|
| Connection issues | Make sure the Blender addon server is running, and the MCP server is configured on Claude. Do not run the uvx command in the terminal. Sometimes the first command won't go through, but after that it starts working. |
| Timeout errors | Try simplifying your requests or breaking them into smaller steps. |
| Blender freezes during a Poly Haven download | Assets are downloaded on Blender's main thread, so the UI stops responding until the transfer finishes. File size grows roughly fourfold per resolution step, so ask for 1k or 2k unless the asset is held close to camera. |
| Poly Pizza download fails with a Cloudflare challenge | static.poly.pizza is behind bot protection and blocks datacenter, VPN and cloud IPs. Your API key is fine - the CDN never sees it. Retry from a normal connection, or download the .glb by hand and use File → Import → glTF 2.0. |
| Have you tried turning it off and on again? | If you're still having connection errors, try restarting both Claude and the Blender server. |
Technical Details
Communication Protocol
The system uses a simple JSON-based protocol over TCP sockets:
- Commands are sent as JSON objects with a
type and optional params
- Responses are JSON objects with a
status and result or message
Limitations & Security Considerations
Warning: The execute_blender_code tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments. ALWAYS save your work before using it.
- Poly Haven requires downloading models, textures, and HDRI images. If you do not want to use it, please turn it off in the checkbox in Blender.
- Complex operations might need to be broken down into smaller steps.
Telemetry Control
Telemetry is opt-in. Collection of your content is off by default and stays off until you explicitly turn it on.
What is collected by default (no opt-in): a minimal anonymous usage record so I can count active users and see which tools get used — a randomly generated install ID, a session ID, the tool name, whether it succeeded, how long it took, the MCP for Blender and Blender versions, your operating system, and a timestamp.
Never collected without opting in: your prompts, generated code, viewport screenshots, scene data, and trajectory steps.
To opt in — go to Edit → Preferences → Add-ons → MCP for Blender and check the telemetry consent checkbox. Some MCP clients will also offer you a one-time opt-in prompt at the start of a conversation. Opting in adds prompts, generated code, screenshots, and trajectory data to what's collected; see the TnC for details. You can turn it back off in the same place at any time.
To turn off telemetry entirely, including the minimal anonymous usage record, set an environment variable:
DISABLE_TELEMETRY=true uvx mcp-for-blender
Or add it to your MCP config:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["mcp-for-blender"],
"env": {
"DISABLE_TELEMETRY": "true"
}
}
}
}
Telemetry data is not linked to your name or account. It may be used to improve MCP for Blender, for research, and to train AI models.
Full detail on what is collected, and the license you grant by opting in, is in TERMS_AND_CONDITIONS.md.
Feedback
We are actively looking for feedback on MCP for Blender. If you have thoughts, share them here.
If you have more detailed feedback, you can schedule a call with us here — we will credit you in the project.
Join the Community
Give feedback, get inspired, and build on top of the MCP: Discord
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Disclaimer
This is a third-party integration and not made by Blender. Made by Siddharth.
Star History
If MCP for Blender is useful to you, consider starring the repo