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 object 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
• Contributors
• Community
• Contributing

Features

Whats New

Full changelog: Releases

• Hunyuan3D 3D model generation
• Viewport screenshot for scene understanding
• Sketchfab model search and import
• Poly Haven asset integration
• Hyper3D Rodin AI model generation
• Remote host support

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

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

uvx not found by your client

GUI clients don't inherit your terminal PATH. Get the full path:

• which uvx (macOS/Linux) or where uvx (Windows)
• Use it as "command" in your config
• Windows: "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

Cursor

Watch Cursor setup video

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

{
    "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. Enable in the BlenderMCP sidebar.

Hyper3D Rodin

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

Hunyuan3D

Tencent 3D generation. 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 restarts:

export BLENDER_HOST=localhost
export BLENDER_PORT=9876

Troubleshooting

• Confirm the addon server is running in the BlenderMCP sidebar
• Do not run uvx manually — the client starts the server
• First command often fails; try again

which uvx   # macOS / Linux
where uvx   # Windows

Use that full path 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 your MCP client and the Blender server.

Technical Details

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

JSON over TCP sockets:

{ "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.

Disable entirely:

DISABLE_TELEMETRY=true uvx blender-mcp

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

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

Contributors

Community

Supporters: CodeRabbit

Contributing

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

See CONTRIBUTING.md and TERMS_AND_CONDITIONS.md.

License

MIT — see LICENSE.

Star History