blender-mcp: driving Blender from an LLM over a local socket

The gap blender-mcp fills between a chat window and a 3D scene

Blender has no MCP server of its own. blender-mcp is a third-party bridge that supplies one, and the README states plainly that it is not made by Blender. The problem it addresses is mechanical: an LLM can describe a scene in text, but it cannot move a vertex, assign a material or read back what is currently selected. blender-mcp exposes those operations as tools the model can call.

The intended user is someone already working inside an MCP-capable client. The README lists Claude Desktop, Claude Code, Codex, Cursor, VS Code, OpenCode and Antigravity as supported clients, and the pitch is that any LLM of your choice can drive the scene. That framing matters. This is not a Blender feature and not a rendering engine; it is a control channel. If you do not already have a client that speaks MCP, the project gives you nothing to talk to.

The capability list is concrete rather than aspirational: create, modify and delete objects, apply and change materials and colors, inspect the current scene, and run arbitrary Python inside Blender. Asset generation is included too, with Poly Haven assets, Sketchfab models, Poly Pizza low-poly models, and AI-generated models through Hyper3D Rodin and Hunyuan3D. Those integrations mean the addon reaches external services, which is worth remembering when you read the credentials section below.

Two processes, one socket: how blender-mcp actually moves data

The architecture is two components, not one. The Blender addon lives in addon.py and creates a socket server inside Blender that receives and executes commands. The MCP server lives in src/blender_mcp/server.py, implements the Model Context Protocol, and connects to that addon.

Data flow runs in one direction at a time. Your MCP client starts the Python server, the server opens a connection to the addon's socket, and the model's tool calls travel that path into Blender. Results come back the same way. Nothing here is a plugin loaded into the client; the client just launches a subprocess, which is why the install instructions are about making that subprocess findable rather than about editing Blender.

The pyproject.toml confirms the shape of the server package. It depends on mcp>=1.9.0,<2 and httpx>=0.27.0, requires Python 3.10 or newer, and exposes a single console script, blender-mcp, pointing at blender_mcp.server:main. The addon itself ships as package data under blender_mcp/bundled/addon.py, which is why the CLI can install it for you. The Dockerfile shows the same server running headless with BLENDER_HOST set to host.docker.internal and BLENDER_PORT set to 9876, with a comment noting that Blender runs on the host and not in the container. That port number is the one to check when a connection silently fails.

Installing blender-mcp and getting a first prompt through

The README insists on one prerequisite before anything else: install uv, and use the official installer rather than pip install uv, which the README warns may not create the uvx command. The per-platform commands are given directly.

# 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"

After that, register the server with your client. For Claude Desktop the README shows a config block placed under Settings, Developer, Edit Config.

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["blender-mcp"]
        }
    }
}

Claude Code and Codex get one-line commands instead.

claude mcp add blender uvx blender-mcp

codex mcp add blender -- uvx blender-mcp

Next, install the addon into Blender from the same CLI.

uvx blender-mcp install-addon

Then enable it in Blender under Edit, Preferences, Add-ons, where it appears as Interface: MCP for Blender. To connect, the README says to press N in the 3D viewport, open the MCP for Blender tab, and click Start MCP Server. The README adds a restriction that is easy to miss: run only one instance of the MCP server, either Cursor or Claude Desktop, not both. If your client was launched from a GUI and reports spawn uvx ENOENT, the fix the README gives is to replace the command with the absolute path from which uvx on macOS or Linux, or where uvx on Windows.

Where blender-mcp breaks, and when it is the wrong tool

The most consequential limitation is stated in the feature table, not buried: code execution means running arbitrary Python code in Blender from the model. That is the mechanism behind much of the flexibility, and it is also the reason the README carries a separate section on limitations and security considerations. If you would not paste a stranger's script into Blender's Python console, you should think carefully before pointing a model at this addon.

The second constraint is environmental. Blender must be running, with the addon enabled and the socket server started, before the model can do anything. There is no headless batch mode described in the README. For a build server that regenerates assets on every commit, that interactive dependency is disqualifying, and a scripted bpy pipeline is the better fit.

The third is client plumbing. MCP clients started from a GUI do not inherit your terminal's PATH, so a configuration that works in a shell can fail in the app. The README documents the ENOENT symptom and the absolute-path workaround, which tells you this is a common enough failure to have earned its own paragraph. There is also the single-instance rule: two clients both holding the socket is not a supported arrangement. And because the addon reaches Poly Haven, Sketchfab, Poly Pizza, Hyper3D Rodin and Hunyuan3D, some workflows depend on network access and on credentials for the hosted services.

blender-mcp against writing bpy scripts by hand

The obvious alternative is not another MCP project; it is Blender's own Python API. A bpy script is deterministic, versionable and runs headless, and it needs no client, no socket and no uv. The difference in approach is who decides what happens next. With a script, you decide, and the script does exactly that every time. With blender-mcp, the model decides which tools to call based on your prompt, and the code-execution capability means the exact operations are not known in advance.

That trade favors blender-mcp during exploration: blocking out a scene, trying a material, asking what is currently in the file. It favors scripts for anything that must be reproduced. A reasonable split is to prototype through the model and then capture the result as a bpy script once the scene looks right, rather than treating a chat session as the source of truth for a production asset. The README does not describe an export path from a conversation to a reproducible script, so that step is on you.

A second comparison is between MCP clients themselves. The README documents per-client setup for Claude Desktop, Claude Code, Codex, Cursor, VS Code, OpenCode and Antigravity, and the practical difference is how each one starts the server and whether it inherits PATH. The server is the same Python process in every case.

Upgrades, credentials, licence and telemetry

The project is at version 1.9.1 in pyproject.toml, and the README has a dedicated Upgrading (existing users) section, which implies the addon and the server are upgraded separately and that mismatched halves are a real scenario. The README does not document rollback, so pinning a version before you upgrade is your own precaution.

Credentials are handled outside the conversation. The README has a Persistent API Credentials section, which exists because the hosted asset services need keys; the README does not spell out the storage mechanism in the text available here, so read that section before entering anything. There is also a Telemetry Control section, meaning telemetry exists and can be turned off. Treat both as things to configure deliberately rather than defaults to accept.

The licence is MIT, declared in pyproject.toml and shown in the README badge. MIT is permissive: it allows commercial use and modification, and it comes with no warranty. This is not legal advice, and the repository also contains a TERMS_AND_CONDITIONS.md file alongside LICENSE, so if you are embedding this in a product, read both. Maintenance looks current rather than dormant: the last push to the default branch was on 2026-09-07, ten days before this writing.

Editorial conclusion

Adopt blender-mcp if you already drive an MCP client such as Claude Desktop, Claude Code, Codex, Cursor, VS Code, OpenCode or Antigravity and you want prompt-driven scene edits without leaving Blender. Skip it if you need a headless, deterministic pipeline or if you cannot accept that the model can run arbitrary Python in your Blender session. Before trusting it with real work, verify three things on your own machine: that your client can spawn uvx, that the addon panel reports a live connection on port 9876, and that you are comfortable with the code-execution and telemetry settings the README documents.

Frequently asked questions

Official sources

1. ahujasid/blender-mcp on GitHub
2. Issues
3. License: MIT
4. Project website
5. README