blender-mcp

MCP for Blender (formerly blender-mcp) is a community-maintained third-party integration for connecting Blender 3D to any LLM, enabling prompt-assisted 3D modeling, scene creation, and manipulation. It is not produced by the official Blender Foundation.

Purpose Use AI to drive Blender for modeling, layout, materials, animation, rigging, and retopology. The AI writes Blender Python scripts itself, while MCP provides capabilities that Python alone cannot accomplish, comprising nine tools in total.

Main capabilities

• The Blender add-on (addon.py) creates a socket server inside Blender to receive and execute commands from the MCP server.
• The MCP server (src/blender_mcp/server.py) implements the Model Context Protocol and connects to the Blender add-on.
• Set up the AI application and Blender add-on with a single command: automatically install uv (if needed), detect MCP clients on the machine (Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin Desktop/Windsurf, OpenCode, Antigravity), let the user choose which ones to set up, then install and enable the Blender add-on. Existing configurations only gain one blender entry, and a .bak backup is saved for each modified file. (Windows uses PowerShell installation; if uv is already installed, you can use uvx mcp-for-blender setup.)
• Supports importing AI 3D models generated by Hunyuan3D, Tripo, and Hyper3D Rodin directly into Blender, with no need to bring your own API key. When using the official Tencent Cloud API, you need to choose the corresponding service based on your account's region; sending international-edition credentials to the mainland endpoint will result in AuthFailure.SignatureFailure or ResourceUnavailable, in which case you need to check the toggle switch under Tencent Hunyuan 3D → Official API in the sidebar.
• Poly Haven integration: about 2,400 HDRIs, texturesand models, all CC0 free, no API key, no account, and no rate limits to worry about. Just check Poly Haven in the 3D view sidebar. Example: "Light the scene with an overcast afternoon HDRI, and apply a rusty metal texture to the wall" — the AI will call search_assets(source="polyhaven", query="overcast afternoon", asset_type="hdris"); previews=3 will attach thumbnails of the top results before consuming bandwidth; import_asset(source="polyhaven", id="...", asset_type="textures", apply_to=["Wall"]) can download and apply the texture in a single call. Search can also be filtered by category path or attributes, such as weather and time of day for HDRIs, and surface use and condition for textures; unknown attributes will return a valid-attribute error. Models are imported from .bl files.
• The Codex plugin provides an in-chat live viewport (clicking an object attaches it to the next message), thumbnail pickers for Poly Haven, Sketchfab, and Poly Pizza, and @ mentions for scene objects, materials, and collections.

How to use Prerequisites: Blender 3.0 or newer, Python 3.10 or newer, the uv package manager.

1. Install uv (official installer, do not use pip install uv).
2. Add the MCP server to the client (configuration instructions for each client are in the repository: Claude for Desktop, Claude Code, Codex, Cursor, Visual Studio Code, OpenCode, Antigravity).
3. Install the Blender add-on: in Blender, go to Edit → Preferences → Add-ons → enable Interface: MCP for Blender. The add-on starts its server when Blender is open. You can check by pressing N in the 3D viewport to open the MCP for Blender tab (if it is not running, click Start MCP Server). Connection: In Blender, open the 3D view sidebar (press N), find MCP for Blender tab, check the required options, click Connect to Claude, and make sure the MCP server is running in the terminal. Once connected, a hammer icon with tools will appear in Claude. One-click install: Windows (PowerShell); if uv is already installed, use uvx mcp-for-blender setup. Then fully quit and restart the AI app (on Windows, quit from the system tray), open Blender, and let it build content. Environment variables: Blender connection can be configured; they can also be passed via CLI flags, which take precedence over environment variables, making it convenient to run multiple Blender instances side by side (each instance needs to set its own port in the Blender add-on panel to match). Docker: The MCP server can run in a container while Blender itself still runs on the host. The image defaults to BLENDER_HOST=host.docker.internal; on Linux, switch to host networking. To enable safe mode in the container, add "-e", "BLENDER_MCP_SAFE_MODE=1". Safe mode: By default, the AI can run arbitrary Python code in Blender. Setting BLENDER_MCP_SAFE_MODE=1 checks and blocks high-risk code before each script run (such as directly reading/writing files, running other programs, accessing the network, or installing code that runs continuously). Normal Blender work (modeling, materials, rendering, saving, import/export) can still proceed; blocked scripts are returned to the AI along with the reason so it can correct and retry. Path issues: MCP clients launched from the GUI do not inherit the terminal PATH, so writing "command": "uvx" directly may report spawn uvx ENOENT; you can use the full path to uvx instead, or on Windows wrap it as "command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"]. After changing this, fully quit and restart the client. Python version: uv determines the Python used to run the server. If conda/pyenv/asdf or a newer CPython is present, you can pin Python 3.11 and prefer the uv-managed interpreter (UV_PYTHON_PREFERENCE=only-managed). Clearing the cache can resolve failed retry issues. On restricted machines, you can install with pipx and point to the command. Upgrade: Updates the MCP server and all installed copies of the Blender add-on, and keeps .bak files; it will not downgrade an add-on newer than the release, nor modify locally edited copies; add --dry-run to preview. Use @latest the first time (versions earlier than 2.1.7 do not have the update command). After updating, restart the MCP client, and in Blender restart the add-on or disable and re-enable it, then click Start MCP Server.

Use cases Suitable for users who want to use any LLM within Blender for prompt-assisted modeling, scene setup, material and asset search, animation and rigging, and also for workflows that need to connect AI 3D model generation services to Blender.

Limitations and notes

• This is a third-party integration, not made officially by Blender.
• The add-on's socket server has no authentication or encryption; anyone who can access that port can run Python within Blender. Unless on a trusted network, it should remain on localhost; it is not recommended to point --host / BLENDER_HOST directly at a remote machine, prefer an SSH tunnel.
• Only one MCP server instance should run at a time (choose either Cursor or Claude Desktop, do not run both at once).
• By default, the AI can execute arbitrary Python; safe mode must be enabled via BLENDER_MCP_SAFE_MODE=1.
• Other specific features, fees, and pricing information are not yet provided.