BlenderMCP: Bridging Claude AI and 3D Modeling Environments

BlenderMCP serves as a conduit, linking the advanced reasoning capabilities of Claude AI with the powerful 3D creation software, Blender, utilizing the Model Context Protocol (MCP). This integration enables sophisticated, prompt-driven workflows for generating, refining, and orchestrating 3D scenes and assets.

Official Status Warning: This project maintains no formal website presence. Any external web locations claiming official affiliation are unauthorized and utilized at the user's sole discretion.

Comprehensive Setup Guide

Engage with the Collective

Share insights, find creative motivation, and contribute to the MCP ecosystem here: Discord Server Link

Acknowledged Patrons

^{Gratitude to our key supporters:}

### [Warp: The Optimized Developer Terminal](https://www.warp.dev/blender-mcp) [Compatible across MacOS, Linux, and Windows platforms](https://www.warp.dev/blender-mcp)

Additional Contributors:

CodeRabbit Platform

Satish Goda's Contribution

Support the Initiative:

Sponsor Development Efforts

Recent Updates (Version 1.2.0)

Integrated functionality to capture and interpret Blender viewport imagery for enhanced scene comprehension.
Capability added for querying and retrieving assets from the Sketchfab library.

Historical Enhancements:

Native API integration for sourcing environment maps and assets from Poly Haven.
Implementation of Hyper3D Rodin for on-demand procedural 3D geometry generation.
For new users, direct transition to the installation steps is recommended. Established users should follow the subsequent update procedure:
Download the newest iteration of addon.py and substitute the previous version, subsequently registering it within Blender.
Re-registering the MCP service within Claude (by removal and re-addition) often resolves minor connection glitches.

Core Functionality

Bilateral Communication: Establishes a persistent, socket-based link between the Claude inference engine and Blender.
Geometric Manipulation: Permits the AI to conceive, modify, and purge three-dimensional entities within the scene.
Material Definition: Enables control over surface properties, including color schemes and shader assignments.
Scene Diagnostics: Allows retrieval of granular data describing the current state of the Blender workspace.
Script Execution: Grants the ability to securely run arbitrary Python commands within the Blender environment directly from AI prompts.

Architectural Elements

The setup comprises two essential parts:

Blender Plugin (addon.py): This component resides inside Blender, initiating a listener socket to accept and process external instructions.
MCP Handler (src/blender_mcp/server.py): A standalone Python process that adheres to the MCP specification, managing the connection layer to the Blender plugin.

Setup Instructions

Prerequisites

Blender software, version 3.0 or later.
Python runtime environment, version 3.10 or newer.
The 'uv' package manager utility:

For macOS Users:

brew install uv

For Windows Users:

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

Followed by updating the system PATH:

set Path=C:\Users\nntra\.local\bin;%Path%

Refer to the official documentation for other operating systems: Install uv Guide

Crucial Note: UV must be installed before proceeding.

Environment Configuration Variables

The connection parameters can be customized via the following environment settings:

BLENDER_HOST: Specifies the network address for the Blender socket listener (Default: "localhost").
BLENDER_PORT: Defines the communication port (Default: 9876).

Example of setting variables:

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

Integrating with Claude Desktop

Consult this video for setup guidance (Assumes 'uv' is already configured).

Navigate within Claude to Settings > Developer > Edit Config, and modify claude_desktop_config.json to include this server definition:

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

Cursor Editor Integration

Mac users should navigate to Settings > MCP and input the following configuration: - Use "Add New Global MCP Server" for system-wide access, or create/update .cursor/mcp.json in the project root for local scope.

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

Windows users should go to Settings > MCP > Add Server and configure it as follows:

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

Cursor Integration Walkthrough Video

Critical Warning: Only one MCP server instance (either Claude Desktop or Cursor) should be active concurrently.

Visual Studio Code Integration

Prerequisite: Ensure Microsoft Visual Studio Code is installed.

Installing the Blender Plugin

Retrieve the addon.py file from this repository.
Launch Blender.
Navigate to Edit > Preferences > Add-ons.
Select the "Install..." button and locate the downloaded addon.py.
Activate the addon by checking the box labeled "Interface: Blender MCP".

Operational Use

Establishing Connectivity

Within Blender, access the 3D View sidebar (shortcut: 'N' key if hidden).
Locate and select the "BlenderMCP" panel.
Optionally, activate the Poly Haven integration checkbox if external assets are desired.
Initiate the connection process by clicking "Connect to Claude".
Verify that the MCP server process is active and running in your command-line interface.

Interacting with Claude

Once the configuration is registered in Claude and the Blender plugin is listening, a specialized tool icon (resembling a hammer) will appear, signifying the Blender MCP interface.

Supported Actions

Querying details about the active scene and its constituent objects.
Programmatic generation, removal, and modification of geometric primitives.
Assigning or developing new material definitions for objects.
Executing arbitrary Python scripts within the Blender context via AI command.
Programmatic retrieval of appropriate models, textures, and HDRIs from the Poly Haven repository.
Leveraging Hyper3D Rodin for AI-synthesized 3D geometry.

Command Illustrations

Examples of AI directives:

"Construct a cavernous dungeon environment featuring a dragon protecting a hoard of gold." Visual Demonstration
"Compose a coastal ambiance utilizing HDRIs, surface textures, and corresponding models (e.g., stones, flora) sourced from Poly Haven." Visual Demonstration
"Generate a complete Blender scene based on this provided reference image." Visual Demonstration
"Synthesize a rendering of a garden gnome using the Hyper3D generation service."
"Report on the current scene metrics, subsequently generating a Three.js compatible sketch of the setup." Visual Demonstration
"Change the color scheme of this object to a reflective red metallic finish."
"Instantiate a spherical primitive and position it directly above the existing cuboid object."
"Set the scene illumination to mimic professional studio lighting conditions."
"Orient the camera view towards the center of the composition and switch the perspective to orthographic."

Hyper3D Service Notes

Hyper3D's introductory tier limits daily asset generation. Exceeding this quota necessitates waiting for the daily reset or acquiring a personalized key via hyper3d.ai or fal.ai.

Troubleshooting Guide

Connectivity Failures: Verify the Blender plugin server is active and the MCP configuration is correct in Claude. Do not execute the uvx command in the terminal if running through the IDE integration. Initial commands may fail; subsequent attempts usually succeed.
Request Timeouts: Consider breaking complex instructions into sequential, smaller operations or streamlining the prompt content.
Poly Haven Errors: Claude's interaction with external APIs can occasionally be inconsistent.
The Classic Reboot: If connection persistence remains an issue, restart both the Claude application and the dedicated Blender MCP listener.

Technical Specifications

Data Exchange Protocol

The communication layer relies on TCP sockets transmitting standardized JSON payloads:

Outgoing Data (Commands): JSON structures containing a mandatory type field and optional params payload.
Incoming Data (Responses): JSON structures indicating status alongside either a result payload or an error message.

Constraints & Security Postures

The execute_blender_code utility permits the execution of any Python script within Blender's context. This presents considerable capability but demands prudence, especially in live operational systems. Always commit or save your project state prior to invoking this function.
Poly Haven downloads external assets (textures, geometry, HDRIs). This feature can be disabled via its dedicated checkbox in the Blender UI if unwanted.
Intricate modeling tasks might require decomposition into discrete, manageable steps for optimal AI performance.

Contributions Policy

We welcome external input! Please submit any proposed enhancements as a Pull Request.

Project Attribution

This extension is a community effort, independent of the official Blender foundation. Developed by Siddharth

blender-ai-interface

Author

ahujasid

Quick Info

Actions

Tags