Blender MCP with Claude Code and Codex: setup guide

Connect Blender to Claude Code or Codex with MCP for Blender (formerly blender-mcp): add-on, one-line setup, first prompts, what it can do, safety and troubleshooting.

7 minutes Matěj Žalmánek 2026-10-26

“Add a low-poly tree, three rocks and warm evening light” — and the scene appears in Blender. That is what Blender MCP does: it connects an AI agent to Blender so the agent can create objects, apply materials and run Blender's Python for you. Most guides show it with Claude Desktop; this one shows how to set up Blender MCP with Claude Code and Codex, with the current package name, and what to watch out for.

1. What is Blender MCP

Blender MCP is a community, open-source (MIT) project that lets AI models control Blender through the Model Context Protocol. It has two parts:

• a Blender add-on that runs a small socket server inside Blender and executes the commands it receives;
• an MCP server that your AI agent starts and that talks to the add-on.

It is not made by the Blender Foundation. The project used to be published as blender-mcp; it is now mcp-for-blender — many older tutorials still use the old name.

2. What you need

• Blender 3.0 or newer;
• Python 3.10 or newer;
• the uv package manager, installed with uv's official installer (the project explicitly advises against pip install uv);
• Claude Code or Codex.

3. Step 1: install the Blender add-on

uvx mcp-for-blender install-addon

Then in Blender open Edit → Preferences → Add-ons and enable Interface: MCP for Blender. (The project also offers a one-line installer script and uvx mcp-for-blender setup; the manual way above shows you what is happening.)

4. Step 2: connect Blender MCP to Claude Code

claude mcp add blender uvx mcp-for-blender

That is the whole configuration. Add --scope user if you want Blender available in every project, not just the current one. Check it with claude mcp list, or /mcp inside a session.

5. Or: connect Blender MCP to Codex

codex mcp add blender -- uvx mcp-for-blender

Or write it into ~/.codex/config.toml yourself:

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]

Codex keeps its own MCP configuration — it does not reuse what you set up for Claude Code or Cursor. codex mcp list shows what it has.

6. Step 3: start the server in Blender and test it

1. Open Blender and press N in the 3D viewport to open the sidebar.
2. Open the MCP for Blender tab and start the server (the button label differs between versions — “Start MCP Server” or “Connect”).
3. Start your agent and begin with something read-only: “Describe the current Blender scene.” If it answers with your objects, the connection works.
4. Then something small: “Add a cube with a red material at the origin.”

The add-on listens on localhost:9876 by default; BLENDER_HOST and BLENDER_PORT change it.

7. What Blender MCP can do

• create, modify and delete objects, apply materials;
• run arbitrary Blender Python (execute_blender_code) — the most powerful and most dangerous tool;
• look at the result through the viewport, a camera or a render, so the agent can check its own work;
• pull assets from Poly Haven, Sketchfab and Poly Pizza;
• generate 3D models through services such as Meshy, Tripo, Hyper3D Rodin and Hunyuan3D (these need their own accounts).

Prompts that work well are specific and step by step: set up the scene, then the lighting, then the materials — and let the agent look at a render between steps. Blender MCP is great at driving Blender; it does not turn a model into a skilled 3D artist.

8. Safety: save your work first

• Save before you start. execute_blender_code runs any Python the agent writes, and the project itself says to always save your work before using it.
• Keep it on localhost. The socket server in the add-on has no authentication and no encryption.
• Keep approvals on. Let the agent ask before it runs code in Blender — in Claude Code that is the default; see Claude Code permission modes.
• Telemetry: a minimal anonymous usage record is sent by default; DISABLE_TELEMETRY=true turns all telemetry off. Collecting prompts or scene content is opt-in.

9. Troubleshooting Blender MCP

• “uvx: command not found” or the server never starts — the agent does not see uv on its PATH. Run which uvx and use the full path as the command. Apps started from the macOS Dock often have a different PATH than your terminal.
• The agent sees no Blender tools — check claude mcp list or codex mcp list, and that the server is started in Blender's sidebar.
• Connection refused — Blender is not running, the add-on is disabled, or something else uses port 9876.
• Strange errors with two clients — run only one MCP server instance at a time, for example not in Cursor and Claude Code at once.
• Blender freezes during a download — Poly Haven downloads run on Blender's main thread; wait for them to finish.
• An old tutorial does not match — it probably uses the old name blender-mcp and older add-on labels. Follow the current README and use mcp-for-blender.

Do you see it differently? Write to support@coden-app.com.