---

BlenderMCP connects Blender 3D to Claude AI (and any other LLM) through the Model Context Protocol. It enables prompt-driven 3D modeling, scene creation, and real-time manipulation directly from your AI assistant.

---

Table of Contents

• Features
• Whats New
• Quick Start
• Installation
• Usage
• Integrations
• API Credentials
• Troubleshooting
• Technical Details
• Security and Telemetry
• Community
• Contributing

---

Features

	Capability	Description
🔁	Two-way communication	Real-time socket bridge between Claude and Blender
🧊	Object manipulation	Create, move, scale, and delete 3D objects via prompts
🎨	Material control	Apply, modify, and generate materials and colors
🔍	Scene inspection	Full scene state — objects, lights, cameras
📷	Viewport screenshot	Let the AI see the Blender viewport
🐍	Code execution	Run arbitrary Python inside Blender
🌍	Poly Haven	Download HDRIs, textures, and models via API
🤖	AI model generation	3D assets via Hyper3D Rodin and Hunyuan3D
🗂️	Sketchfab	Search and import 3D models
🌐	Remote host	Run the MCP server on a remote machine

---

Whats New

Full changelog: Releases

• Hunyuan3D 3D model generation
• Viewport screenshot for scene understanding
• Sketchfab model search and import
• Poly Haven asset integration (HDRIs, textures, models)
• Hyper3D Rodin AI model generation
• Remote host support
• Anonymous telemetry with full user control

Updating from an older version:

1. Download the latest addon.py and replace it in Blender
2. Remove and re-add the MCP server in your client config

---

Quick Start

# macOS
brew install uv

Add to Claude > Settings > Developer > Edit Config > claude_desktop_config.json:

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

Install the Blender addon, click Connect, and start prompting.

---

Installation

Prerequisites

Requirement	Minimum version
Blender	3.0
Python	3.10
uv	Latest

Install uv:

macOS

brew install uv

Windows

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

Add to PATH (restart your client after):

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

Linux

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

Open a new shell after installing.

Do not use pip install uv — it may not create the uvx command the MCP client needs.

---

uvx not found by your client

GUI clients (Claude Desktop, Cursor, VS Code from Dock/Start menu) do not inherit your terminal PATH.

• Find the full path: which uvx (macOS/Linux) or where uvx (Windows)
• Use it as "command" in your config, e.g. /opt/homebrew/bin/uvx
• Windows wrapper: "command": "cmd", "args": ["/c", "uvx", "blender-mcp"]
• Fully quit and relaunch your client after any config change

---

Claude Desktop

Watch setup video

Claude > Settings > Developer > Edit Config > claude_desktop_config.json:

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

Pin Python 3.11 (recommended for conda / pyenv machines)

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "blender-mcp"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}

Install without uv (locked-down machines)

pipx install blender-mcp
pipx ensurepath

Use the path from which blender-mcp as "command" and omit args.

---

Cursor

Watch Cursor setup video

macOS / Linux

Settings > MCP > Add new global MCP server:

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

Windows

Settings > MCP > Add Server:

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

Run only one MCP server at a time — Cursor or Claude Desktop, not both.

---

VS Code

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

---

OpenCode

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "blender-mcp"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

---

Claude Code CLI

claude mcp add blender uvx blender-mcp

---

Blender Addon

1. Download addon.py
2. In Blender: Edit > Preferences > Add-ons > Install...
3. Select addon.py
4. Enable "Interface: Blender MCP"

---

Usage

Starting the Connection

1. Open the 3D View sidebar (press N if not visible)
2. Go to the BlenderMCP tab
3. (Optional) Enable Poly Haven for asset downloads
4. Click Connect to Claude

When connected, Claude shows a hammer icon confirming Blender tools are active:

---

Example Prompts

Prompt	Demo
"Create a low poly dungeon with a dragon guarding gold"	Watch
"Beach scene with Poly Haven HDRIs, rocks, and vegetation"	Watch
"Recreate this reference image as a Blender scene"	Watch
"Export the scene and build a Three.js sketch from it"	Watch
"Generate a garden gnome with Hyper3D"	—
"Make this car red and metallic"	—
"Studio lighting, isometric camera"	—

---

Integrations

Poly Haven

Download HDRIs, textures, and 3D models directly into Blender. Enable in the BlenderMCP sidebar.

Hyper3D Rodin

AI-generated 3D models. Free trial has a daily limit — get your own key at hyper3d.ai or fal.ai.

Hunyuan3D

Tencent 3D generation model. Configure credentials in Blender addon preferences.

Sketchfab

Search and import 3D models into your scenes.

---

API Credentials

Store in Edit > Preferences > Add-ons > Blender MCP to persist across Blender restarts:

Credential	Environment variable
Sketchfab API Key	BLENDERMCP_SKETCHFAB_API_KEY
Hyper3D API Key	BLENDERMCP_HYPER3D_API_KEY
Hunyuan3D SecretId	BLENDERMCP_HUNYUAN3D_SECRET_ID
Hunyuan3D SecretKey	BLENDERMCP_HUNYUAN3D_SECRET_KEY
Hunyuan3D API URL	BLENDERMCP_HUNYUAN3D_API_URL

Remote / CI:

export BLENDER_HOST=localhost
export BLENDER_PORT=9876

---

Troubleshooting

Connection issues

• Confirm the addon server is running in the BlenderMCP sidebar tab
• Confirm the MCP server is in your client config — do not run uvx manually
• First command often fails; try again

spawn uvx ENOENT

Client cannot find uvx. Get its absolute path:

which uvx   # macOS / Linux
where uvx   # Windows

Use that as "command" in your config.

Timeout / complex operations

Break the request into smaller, sequential prompts.

Python version conflicts (conda / pyenv)

"args": ["--python", "3.11", "blender-mcp"],
"env": { "UV_PYTHON_PREFERENCE": "only-managed" }

Clear cache: uv cache clean blender-mcp && uvx --refresh blender-mcp

Still broken?

Restart both your MCP client and the Blender server.

---

Technical Details

Architecture

LLM Client  <-- MCP -->  MCP Server (src/blender_mcp/server.py)  <-- TCP -->  Blender Addon (addon.py)

Protocol

JSON over TCP sockets (default port: 9876):

{ "type": "create_object", "params": { "type": "SPHERE", "name": "Ball" } }
{ "status": "success", "result": { "name": "Ball", "location": [0, 0, 0] } }

---

Security and Telemetry

execute_blender_code runs arbitrary Python in Blender. Save your work before using it.

BlenderMCP collects fully anonymous usage data.

Control telemetry

In Blender: Edit > Preferences > Add-ons > Blender MCP > telemetry checkbox

• Enabled: anonymized prompts, code, screenshots
• Disabled: tool name, success/failure, duration only

Disable entirely:

DISABLE_TELEMETRY=true uvx blender-mcp

Or in config: "env": { "DISABLE_TELEMETRY": "true" }

---

Community

Supporters: CodeRabbit

---

Contributing

Pull requests are welcome.

1. Fork the repository
2. Create a branch: git checkout -b feature/your-feature
3. Commit and open a PR

See TERMS_AND_CONDITIONS.md for usage terms.

---

License

MIT — see LICENSE.

---