# Blender MCP + Claude — Complete Setup & Usage Guide

Blender MCP connects [Blender](https://www.blender.org/)  to Claude AI through the **Model Context Protocol (MCP)**, allowing Claude to directly create, modify, and render 3D models in Blender using natural language. This guide covers everything you need to get Claude and Blender working together — from initial installation to advanced prompt techniques.

Whether you’re using **Claude Desktop**, **Claude Code**, or the **Anthropic API**, this guide has you covered. The setup takes about 5–10 minutes and costs nothing — Blender MCP is free and open source.

Want a ready-to-use Blender AI tool without relying on external APIs or subscriptions? Try 3D-Agent — AI and a broader toolset are included, with no MCP configuration.

[See 3D-Agent →](https://3d-agent.com/?utm_source=blendermcp.org&utm_medium=referral&utm_campaign=managed_path_v1&utm_content=setup_claude_top)

[Full Installation & Demo](https://www.youtube.com/watch?v=-k3bw1M0Ixg)

## Prerequisites[](https://blendermcp.org/setup/claude#prerequisites)

Before you begin, make sure you have:

-   **Blender 3.0 or newer** — [Download from blender.org](https://www.blender.org/download/) . Blender 4.x recommended.
-   **Python 3.10 or newer** — Usually bundled with your OS. Check with `python3 --version`.
-   **Claude Desktop app** — [Download from claude.com](https://claude.com/download)  (or use Claude Code CLI).
-   **An Anthropic account** — Free tier works, but Pro gives better results for complex scenes.

> You must install the **uv package manager** before proceeding. The MCP server will not work without it.

## Step 1: Install UV Package Manager[](https://blendermcp.org/setup/claude#step-1-install-uv-package-manager)

The Blender MCP server runs via `uvx` (part of the uv toolchain). Install it for your platform:

**macOS**

**Windows**

**Linux**

### macOS

```bash
brew install uv
```

Verify installation:

```bash
uv --version
```

### Windows

Open PowerShell and run:

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Then add uv to your PATH (you may need to restart Claude Desktop after):

```powershell
$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")
```

### Linux

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

> Full uv installation docs: [docs.astral.sh/uv/getting-started/installation](https://docs.astral.sh/uv/getting-started/installation/)

## Step 2: Configure Claude Desktop (claude\_desktop\_config.json)[](https://blendermcp.org/setup/claude#step-2-configure-claude-desktop-claude_desktop_configjson)

Open Claude Desktop and navigate to **Settings → Developer → Edit Config**. This opens your `claude_desktop_config.json` file. Add the Blender MCP server:

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

Save the file and **restart Claude Desktop** for changes to take effect.

> **Where is the config file?**
>
> -   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
> -   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

### Using Claude Code Instead[](https://blendermcp.org/setup/claude#using-claude-code-instead)

If you prefer the Claude Code CLI, you can add the MCP server with a single command:

```bash
claude mcp add blender uvx blender-mcp
```

No config file editing needed — Claude Code handles it automatically.

## Step 3: Install the Blender Addon[](https://blendermcp.org/setup/claude#step-3-install-the-blender-addon)

The Blender addon creates a socket server inside Blender that receives commands from Claude.

### Download the addon[](https://blendermcp.org/setup/claude#download-the-addon)

Download `addon.py` from the [Blender MCP GitHub repository](https://github.com/ahujasid/blender-mcp) .

### Install in Blender[](https://blendermcp.org/setup/claude#install-in-blender)

Open Blender → **Edit → Preferences → Add-ons** → Click **“Install…”** → Select the downloaded `addon.py` file.

### Enable the addon[](https://blendermcp.org/setup/claude#enable-the-addon)

Check the box next to **“Interface: Blender MCP”** to activate it.

## Step 4: Start the MCP Server[](https://blendermcp.org/setup/claude#step-4-start-the-mcp-server)

With the addon installed, you need to start the connection:

### Open the BlenderMCP panel[](https://blendermcp.org/setup/claude#open-the-blendermcp-panel)

In Blender’s 3D Viewport, press **N** to open the sidebar, then find the **“BlenderMCP”** tab.

### Enable Poly Haven (optional)[](https://blendermcp.org/setup/claude#enable-poly-haven-optional)

Turn on the Poly Haven checkbox if you want access to free HDRIs, textures, and 3D models from [polyhaven.com](https://polyhaven.com/) .

### Click “Connect to Claude”[](https://blendermcp.org/setup/claude#click-connect-to-claude)

This starts the socket server inside Blender. You should see a status message confirming the connection.

> **Only run one MCP server instance at a time.** If you have the MCP server running in both Cursor and Claude Desktop, you’ll get connection conflicts. Pick one.

## Step 5: Your First 3D Model with Claude[](https://blendermcp.org/setup/claude#step-5-your-first-3d-model-with-claude)

Open Claude Desktop (or Claude Code). You should see a **hammer icon** indicating MCP tools are available. Try these prompts:

-   _“Create a low poly dungeon scene with a dragon guarding a pot of gold”_
-   _“Create a beach vibe using HDRIs and models from Poly Haven”_
-   _“Make a red metallic sphere floating above a blue cube”_
-   _“Set up studio lighting and point the camera at the scene with an isometric view”_
-   _“Generate a 3D model of a garden gnome through Hyper3D”_

Claude can create objects, apply materials, set up lighting, download Poly Haven assets, generate 3D models via Hyper3D Rodin, and even execute arbitrary Python code in Blender.

> **Pro tip:** Start with simple requests and build complexity. Claude works best when you describe the end result rather than individual steps. If a complex scene fails, break it into smaller prompts.

## Troubleshooting Common Issues[](https://blendermcp.org/setup/claude#troubleshooting-common-issues)

### ”Connection refused” or “MCP server not found”[](https://blendermcp.org/setup/claude#connection-refused-or-mcp-server-not-found)

-   Make sure the Blender addon server is running (check the BlenderMCP sidebar panel)
-   Restart Claude Desktop after editing the config file
-   Verify uv is installed: `uv --version`
-   Do NOT run `uvx blender-mcp` manually in the terminal — Claude Desktop handles this

### ”Timeout” errors[](https://blendermcp.org/setup/claude#timeout-errors)

-   Complex operations may take longer than expected. Try simplifying your request.
-   Break large scenes into smaller, sequential prompts.

### First command doesn’t work[](https://blendermcp.org/setup/claude#first-command-doesnt-work)

This is a known quirk. Sometimes the first command after connecting won’t go through. Send a second message and it usually starts working.

### Poly Haven assets not loading[](https://blendermcp.org/setup/claude#poly-haven-assets-not-loading)

Claude can be unpredictable with Poly Haven integration. If it’s not working, try being more specific about what you want (e.g., _“Download a forest HDRI from Poly Haven and set it as the world background”_).

### Windows PATH issues[](https://blendermcp.org/setup/claude#windows-path-issues)

If Claude can’t find `uvx`, make sure the uv bin directory is in your system PATH. Restart Claude Desktop after modifying PATH variables.

## Claude Desktop vs Claude Code vs API — Which to Use[](https://blendermcp.org/setup/claude#claude-desktop-vs-claude-code-vs-api--which-to-use)

| Method | Best For | Setup Difficulty |
| --- | --- | --- |
| **Claude Desktop** | Visual artists, beginners | Easiest — GUI config |
| **Claude Code** | Developers, terminal users | Easy — one CLI command |
| **Anthropic API** | Custom integrations, automation | Advanced — code required |

**Claude Desktop** is the recommended starting point for most users. It provides a visual chat interface and automatically manages the MCP server lifecycle.

**Claude Code** is ideal if you’re already comfortable in the terminal and want to combine Blender MCP with coding workflows.

**The Anthropic API** gives you full programmatic control and is best for building automated 3D asset pipelines or custom tools on top of Blender MCP.

## Example Prompts That Work Well[](https://blendermcp.org/setup/claude#example-prompts-that-work-well)

Here are proven prompts from the Blender MCP community:

| Prompt | What It Does |
| --- | --- |
| _”Create a low poly scene in a dungeon, with a dragon guarding a pot of gold”_ | Full scene composition with multiple objects |
| _”Create a beach using HDRIs, textures, and models from Poly Haven”_ | Environment design with real assets |
| _”Give a reference image, and create a Blender scene out of it”_ | Reference-based scene creation |
| _”Generate a 3D model of a garden gnome through Hyper3D”_ | AI 3D model generation |
| _”Get info about the current scene, and make a Three.js sketch from it”_ | Scene export to web |
| _”Make this car red and metallic”_ | Material modification |
| _”Point the camera at the scene, and make it isometric”_ | Camera and rendering setup |

## Is Blender MCP Free?[](https://blendermcp.org/setup/claude#is-blender-mcp-free)

**Yes.** Blender MCP is 100% free and open source ([MIT License](https://github.com/ahujasid/blender-mcp) ). Blender itself is also free. The only cost is your Claude subscription — the free tier works, but Claude Pro ($20/mo) gives significantly better results for complex 3D scenes.

If you would rather self-host the model instead of paying for a hosted one, our [Ollama local setup guide](https://blendermcp.org/setup/ollama) covers that advanced path — it needs a capable GPU, substantially more setup and operation, and generally produces weaker results than leading cloud models for complex Blender work.

## How Does Blender MCP Work?[](https://blendermcp.org/setup/claude#how-does-blender-mcp-work)

Blender MCP uses a two-component architecture:

1.  **Blender Addon** (`addon.py`) — creates a socket server inside Blender that listens for commands
2.  **MCP Server** (`server.py`) — translates between Claude’s MCP protocol and Blender’s socket server

When you send a message in Claude, the MCP server receives it, converts it to a Blender command, sends it through the socket to the addon, and returns the result. For a deep technical explanation, see our [MCP Server architecture guide](https://blendermcp.org/server).

Using a different AI client?

[Cursor Setup →](https://blendermcp.org/setup/cursor)[VSCode Setup →](https://blendermcp.org/setup/vscode)[ChatGPT Setup →](https://blendermcp.org/setup/chatgpt)[Gemini Setup →](https://blendermcp.org/setup/gemini)[Ollama Setup →](https://blendermcp.org/setup/ollama)

## FAQ

### Can I use Blender MCP with Claude for free?

Yes. Blender MCP is free and open source. Blender is also free. You only need a Claude account — the free tier works for basic tasks, but Claude Pro ($20/mo) gives better results for complex scenes. Ollama is the advanced alternative: you self-host the model on your own capable GPU instead of paying for a hosted one, at the cost of substantially more setup and generally weaker results for complex Blender work.

### How does Blender MCP work with Claude?

Blender MCP connects Claude to Blender through the Model Context Protocol. A Blender addon creates a socket server, and an MCP server acts as a bridge between Claude and Blender. Claude sends natural language commands that get translated into Blender operations — creating objects, applying materials, setting up lighting, and more.

### Does Claude Desktop support MCP servers?

Yes. Claude Desktop has native MCP support. Go to Settings → Developer → Edit Config to add MCP servers. You can also use Claude Code CLI, which supports MCP via the 'claude mcp add' command.

### What AI models work with Blender MCP?

Blender MCP was designed for Claude but also works with Cursor, VSCode (via Cline/Roo Code), Google Gemini CLI, and local models through Ollama. Any AI client that supports the Model Context Protocol can connect to Blender MCP.

### How to set up Blender MCP?

Install the uv package manager, add the Blender MCP server config to your Claude Desktop config file (claude\_desktop\_config.json), install the Blender addon from the GitHub repo, and click 'Connect to Claude' in Blender's sidebar. The full process takes about 5-10 minutes.

### What can Blender MCP do?

Blender MCP can create, modify, and delete 3D objects; apply and modify materials; set up lighting and cameras; download assets from Poly Haven; generate 3D models via Hyper3D Rodin; execute arbitrary Python code in Blender; and export scene data. It supports Blender 3.0+ and works with multiple AI clients.

Configuration still not cooperating? That is the trade-off of the open-source path — you choose and manage the AI client, model, and config. 3D-Agent includes the AI and the toolset instead. [Compare Blender MCP with 3D-Agent →](https://blendermcp.org/compare/blender-mcp-vs-3d-agent)