BlenderMCP

Prompt-assisted 3D modeling, scene creation, and manipulation — driven by AI. [**Website**·](https://blendermcp.org/)[**Full Tutorial**·](https://www.youtube.com/watch?v=lCyQ717DuzQ)[**Discord**·](https://discord.gg/SNqPn4TcKQ)[**Releases**·](https://github.com/ahujasid/blender-mcp/releases)[**Sponsor** Three steps: install`uv`, point your MCP client at the server, install the Blender addon. ``` `# macOS brew install uv # Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` ``` **Warning:**Do not proceed before installing uv. Use the official installer —*not*`pip install uv`. ``` `{ "mcpServers": { "blender": { "command": "uvx", "args": ](https://github.com/sponsors/ahujasid)["blender-mcp"] } } }` ``` See[MCP Client Setupbelow for per-client instructions and one-click install buttons. Then in Blender:**Edit → Preferences → Add-ons**→ enable**Interface: Blender MCP**. In Blender's 3D viewport, press`N`→ open the**BlenderMCP**tab → click**Start MCP Server**. That's it — ask Claude to build something. **Note:**Only run**one**instance of the MCP server (either Cursor or Claude Desktop), not both. - ](#mcp-client-setup)[Quickstart - ](#quickstart)[Features - ](#features)[Components - ](#components)[Installation - ](#installation)[Prerequisites - ](#prerequisites)[Make your client find uvx - ](#make-your-client-find-uvx)[Pin the Python version - ](#pin-the-python-version)[Install without uv - ](#install-without-uv)[Environment Variables - ](#environment-variables)[Claude for Desktop - ](#claude-for-desktop)[Cursor - ](#cursor)[Visual Studio Code - ](#visual-studio-code)[OpenCode - ](#opencode)[Starting the Connection - ](#starting-the-connection)[Using with Claude - ](#using-with-claude)[Capabilities - ](#capabilities)[Example Commands 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 - **Blender**3.0 or newer - **Python**3.10 or newer - **uv**package manager ``` `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` ``` Then add uv to the user path in Windows (you may need to restart Claude Desktop after): ``` `$localBin = "$env:USERPROFILE\.local\bin" $userPath = ](#example-commands)[Environment]::GetEnvironmentVariable("Path", "User") [Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")` ``` ``` `curl -LsSf https://astral.sh/uv/install.sh | sh` ``` It lands in`~/.local/bin`— open a new shell so it's on your PATH. Otherwise, installation instructions are on their website:[Install uv On every OS, use uv's**official installer above — not`pip install uv`**, which may not create the`uvx`command and can hide uv inside an environment your client can't see. **Warning:**Do not proceed before installing uv. MCP clients started from a GUI (Claude Desktop, Cursor, VS Code from the Dock/Start menu) do**not**inherit your terminal's PATH, so a bare`"command": "uvx"`can fail with**`spawn uvx ENOENT`**even though`uvx`works in your terminal. If that happens: - Find uvx's full path —`which uvx`(macOS/Linux) or`where uvx`(Windows) — and use it as`"command"`, e.g.`/opt/homebrew/bin/uvx`or`C:\Users\<you>\.local\bin\uvx.exe`. - On Windows you can instead wrap it:`"command": "cmd", "args": ](https://docs.astral.sh/uv/getting-started/installation/)["/c", "uvx", "blender-mcp"]`. - After any PATH or config change,**fully quit and relaunch**the client (Windows: quit from the system tray, not just the window; macOS:Cmd+Q). *Avoid conda / pyenv / version conflicts.* uv chooses which Python runs the server. On machines with conda (auto-activated base), pyenv, or asdf — or with a newer CPython release that some dependencies do not have wheels for yet — uv can grab an interpreter that makes installation fail. Pin Python 3.11 and prefer uv-managed interpreters to avoid using whatever is on your PATH: ``` `{ "mcpServers": { "blender": { "command": "uvx", "args": ["--python", "3.11", "blender-mcp"], "env": { "UV_PYTHON_PREFERENCE": "only-managed" } } } }` ``` `--python 3.11`still satisfies this package's`requires-python >=3.10`, and`UV_PYTHON_PREFERENCE=only-managed`keeps uv from selecting conda, pyenv, asdf, or system Python first. (The repo's`.python-version`is only a hint for contributors and does**not**affect`uvx`.) If a previous failed attempt keeps replaying after a fix, clear the cache: ``` `uv cache clean blender-mcp && uvx --refresh blender-mcp` ``` On locked-down machines you can skip uvx entirely with[`pipx`, then point your client at the installed command: ``` `pipx install blender-mcp pipx ensurepath # then restart your shell / client` ``` Use the resulting absolute path as`"command"`(find it with`which blender-mcp`/`where blender-mcp`) and omit`args`. The following environment variables can be used to configure the Blender connection: ``` `export BLENDER_HOST='host.docker.internal' export BLENDER_PORT=9876` ``` ](https://pipx.pypa.io)[Watch the setup instruction video(assuming you have already installed uv) Go to**Claude → Settings → Developer → Edit Config →`claude_desktop_config.json`**and include the following: ``` `{ "mcpServers": { "blender": { "command": "uvx", "args": ](https://www.youtube.com/watch?v=neoK_WMq92g)[ "blender-mcp" ] } } }` ``` Use the Claude Code CLI to add the blender MCP server: **macOS**— go to**Settings → MCP**and paste the following: - To use as a global server, use the*"add new global MCP server"*button and paste - To use as a project-specific server, create`.cursor/mcp.json`in the root of the project and paste ``` `{ "mcpServers": { "blender": { "command": "uvx", "args": [ "blender-mcp" ] } } }` ``` **Windows**— go to**Settings → MCP → Add Server**, add a new server with the following settings: ``` `{ "mcpServers": { "blender": { "command": "cmd", "args": [ "/c", "uvx", "blender-mcp" ] } } }` ``` **Note:**Only run**one**instance of the MCP server (either on Cursor or Claude Desktop), not both. *Prerequisites*: Make sure you have[Visual Studio Codeinstalled before proceeding. ``` `{ "mcp": { "blender-mcp": { "type": "local", "command": ](https://code.visualstudio.com/)["uvx", "blender-mcp"], "enabled": true, "environment": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" } } } }` ``` This copies the addon into your Blender addons folder as`blender_mcp.py`. It prints where it wrote to, and keeps a`.bak`of any file it replaces. Optional:`uvx blender-mcp addon-paths`lists detected Blender addons folders. Override the destination with`BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons`. **4.**Enable**Interface: Blender MCP**(search "Blender MCP"). If it doesn't appear yet, click**Install…**and select the copied`blender_mcp.py`/`addon.py`, or restart Blender. **5. Manual alternative**— if the command above can't find your Blender install, or you prefer doing it by hand: download`addon.py`from this repo → in Blender,**Edit → Preferences → Add-ons → Install…**→ select the downloaded`addon.py`→ enable it. Then open the**BlenderMCP**tab in Blender's sidebar (press`N`in the 3D viewport) and click**Start MCP Server**. See[Starting the Connectionbelow. For newcomers, go straight to](#starting-the-connection)[Quickstart. For existing users, see below. ``` `uvx blender-mcp install-addon uvx blender-mcp addon-paths # optional: list detected Blender addons folders` ``` **2.**In Blender:**Preferences → Add-ons**→ disable and re-enable**Interface: Blender MCP**(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. - In Blender, go to the 3D View sidebar (pressNif not visible) - Find the**BlenderMCP**tab - Turn on the checkboxes you'd like to use (see more under](#quickstart)[Capabilitiesbelow) - Click**Connect to Claude** - Make sure the MCP server is running in your terminal 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 the Blender MCP. - Get scene and object information - Create, delete and modify shapes - Apply or create materials for objects - Execute any Python code in Blender - Download the right models, assets and HDRIs through](#capabilities)[Poly Haven - Search and download models from](https://polyhaven.com/)[Sketchfab - AI generated 3D models through](https://sketchfab.com/)[Hyper3D Rodinand](https://hyper3d.ai/)[Hunyuan3D Here are some examples of what you can ask Claude to do: BlenderMCP supports persistent credentials via Blender Add-on Preferences: **Edit → Preferences → Add-ons → Blender MCP** You can store these values there so they survive Blender restarts: - Sketchfab API Key - Hyper3D API Key - Hunyuan3D SecretId / SecretKey - Hunyuan3D API URL For headless setups or CI, credentials can also be injected by environment variables: 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. BlenderMCP collects anonymous usage data to help improve the tool. Telemetry consent is**on by default**, and you can turn it off in two ways: **1. In Blender**— go to**Edit → Preferences → Add-ons → Blender MCP**and uncheck the telemetry consent checkbox. - With consent (checked, the default): view the TnC for more details on data collected. **2. Environment Variable**— completely disable all telemetry by running: ``` `{ "mcpServers": { "blender": { "command": "uvx", "args": ](https://3d.hunyuan.tencent.com/)["blender-mcp"], "env": { "DISABLE_TELEMETRY": "true" } } } }` ``` Telemetry data is not linked to your name or account. It may be used to improve BlenderMCP, for research, and to train AI models.