Blender MCP + Claude — Complete Setup & Usage Guide

Blender MCP connects Blender  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.

Prerequisites

Before you begin, make sure you have:

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

Step 1: Install UV Package Manager

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

brew install uv

uv --version

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

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

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

Step 2: Configure Claude Desktop (claude_desktop_config.json)

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

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

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

Using Claude Code Instead

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

claude mcp add blender uvx blender-mcp

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

Step 3: Install the Blender Addon

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

Step 4: Start the MCP Server

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

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.

Troubleshooting Common Issues

”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

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

First command doesn’t 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

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

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

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

Here are proven prompts from the Blender MCP community:

Is Blender MCP Free?

Yes. Blender MCP is 100% free and open source (MIT License ). 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.

For a fully free setup with no API costs at all, see our Ollama local setup guide.

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.