Blender MCP with Claude Code: Step-by-Step Setup Guide

The Short Answer

To use Blender MCP with Claude Code, install uv, run claude mcp add blender uvx mcp-for-blender, install the Blender add-on with uvx mcp-for-blender install-addon, enable Interface: MCP for Blender in Blender's preferences, and check that blender shows as connected in /mcp. Claude can then build and edit scenes in your running Blender session.

The server is the community project by Siddharth Ahuja, listed on mcp.so as Blender MCP. It was called blender-mcp and is now published on PyPI as mcp-for-blender. According to the project README, old setups that run uvx blender-mcp keep working, but new installs should use the new name. It is a third-party integration, not an official Blender product.

How Blender MCP Works

There are two pieces, and both have to be running:

1. The MCP server (mcp-for-blender). Claude Code starts it for you over stdio. You never run it yourself in a terminal.
2. The Blender add-on. It opens a socket server inside Blender (on localhost, port 9876 by default) that receives commands and runs them.

Claude Code talks to the MCP server, and the MCP server forwards each command to the add-on over that socket. If Blender is closed or the add-on is off, the MCP server starts but every tool call fails.

The server exposes a small set of tools. The main ones are execute_blender_code (run Python in your live Blender), look (see the viewport, camera, multi-angle views or renders), get_scene_info, search_assets and import_asset (Poly Haven, Sketchfab and Poly Pizza), and generate_3d (AI models via Tripo, Hunyuan3D or Hyper3D Rodin). Claude writes Blender Python for most of the modeling work and uses look to check its own results.

Prerequisites

Install uv first. The README is explicit that you should not continue without it:

# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a new terminal afterwards and confirm uvx --version works.

Option A: The One-Command Installer

The project ships an installer that finds the MCP clients on your machine (Claude Code is one of them), lets you pick which to set up, adds a blender entry, and installs and enables the add-on:

# macOS / Linux
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

If you already have uv, uvx mcp-for-blender setup does the same. It keeps your existing config and saves a .bak of each file it changes. As with any piped install script, read it first if you are unsure. If you prefer to see exactly what changes, use the manual steps below.

Option B: Manual Setup in Claude Code

Step 1: Add the MCP server

The command from the README:

claude mcp add blender uvx mcp-for-blender

That saves the server in the default local scope, so it only appears in the current project directory. Blender work is rarely tied to one code repo, so most people want it everywhere. Use user scope for that:

claude mcp add --scope user blender -- uvx mcp-for-blender

A project-scoped entry in .mcp.json looks like this:

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

More on scopes and approvals in our Claude Code MCP guide.

Step 2: Install the Blender add-on

uvx mcp-for-blender install-addon

This copies the add-on into your Blender add-ons folder as blender_mcp.py and prints where it wrote it. If you have several Blender versions, uvx mcp-for-blender addon-paths lists the folders it detected.

Then in Blender:

1. Open Edit → Preferences → Add-ons.
2. Search for "MCP for Blender" and enable Interface: MCP for Blender.
3. If it does not show up, restart Blender, or click Install… and pick the copied file.

Manual fallback: download addon.py from the repo and install it through the same Install… button.

Step 3: Start the add-on's server

The add-on starts its server when Blender opens. To check, press N in the 3D viewport, open the MCP for Blender tab in the sidebar, and click Start MCP Server if it is not running. In the same panel you can tick optional sources such as Poly Haven.

Step 4: Verify in Claude Code

From your terminal:

claude mcp list

Then start claude and run /mcp. You should see blender marked as connected, with its tools listed. A connected server only proves Claude Code can launch the MCP server. To confirm the Blender side, ask for something small:

Use the blender MCP to get the scene info and list every object.

If that returns the default cube, camera and light, everything is wired up.

Example Prompts

Start small and let Claude check its work with the look tool:

• "Create a low poly dungeon scene with a dragon guarding a pot of gold."
• "Make this car red and metallic, then show me a camera view."
• "Light the scene with an overcast afternoon HDRI from Poly Haven and put a rusty metal texture on the wall."
• "Point the camera at the scene and make it isometric."
• "Fill this room with low-poly furniture from Poly Pizza, each item about 1 meter tall."
• "Get information about the current scene and build a three.js sketch of it in this repo."

That last one is where Claude Code shines over a chat app: it can read the scene from Blender and write code into your project in the same session.

Optional Settings

All of these come from the README. Pass environment variables with --env after the server name and before --:

claude mcp add blender --env BLENDER_MCP_SAFE_MODE=1 -- uvx mcp-for-blender

To drive two Blender instances, add a second server with --port 9877 and set the matching port in the second Blender's add-on panel.

API keys for Sketchfab, Poly Pizza, Hyper3D and Hunyuan3D can be stored under Edit → Preferences → Add-ons → MCP for Blender, so they survive restarts.

Troubleshooting

If conda, pyenv or asdf makes uv pick a broken interpreter, pin Python as the README suggests:

claude mcp add blender --env UV_PYTHON_PREFERENCE=only-managed \
  -- uvx --python 3.11 mcp-for-blender

If a failed attempt keeps coming back, clear the cache with uv cache clean mcp-for-blender blender-mcp.

Also run only one client against the add-on at a time. If Claude Desktop or Cursor is also configured with the same server, close it while you use Claude Code.

Safety

execute_blender_code runs arbitrary Python inside Blender, and the add-on's socket has no authentication. Three habits help:

• Save your .blend file before each session. The README says this in bold, and it is right.
• Keep the socket on localhost. Use an SSH tunnel rather than pointing BLENDER_HOST at a remote machine.
• Turn on safe mode when you do not need file or network access from scripts.

Leave Claude Code's tool approval on for execute_blender_code until you trust the workflow. Our MCP security best practices cover the general case.

Next Steps

Blender MCP pairs well with a browser server such as Playwright MCP for checking a three.js export, or with Figma MCP when your 3D work starts from a design. Explore more creative and developer tools in the MCP server directory, or read what an MCP server is if you are new to the protocol.