BlenderMCP

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

Related MCP server: blender-mcp

Features

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

Install uv:

brew install uv

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")

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"]
        }
    }
}

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

pipx install blender-mcp
pipx ensurepath

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

Cursor

Watch Cursor setup video

Settings > MCP > Add new global MCP server:

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

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

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:

Remote / CI:

export BLENDER_HOST=localhost
export BLENDER_PORT=9876

Troubleshooting

• 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

Client cannot find uvx. Get its absolute path:

which uvx   # macOS / Linux
where uvx   # Windows

Use that as "command" in your config.

Break the request into smaller, sequential prompts.

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

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

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.

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.

MCPBlender · blendermcp.org · Not affiliated with the Blender Foundation

If this project helps your workflow, please star it!