blender-mcp-enhanced 1.3.3
Enhanced Blender integration through MCP with shared context, geometry nodes, and advanced tool chaining
License: MIT
Requires Python: >=3.10
Keywords: blender, mcp, ai, 3d, modeling, geometry-nodes, procedural



# BlenderMCP Enhanced - Advanced Blender AI Integration

🚀 **Enhanced fork** of BlenderMCP with **shared context**, **geometry nodes**, and **advanced tool chaining** capabilities.

BlenderMCP Enhanced connects Blender to Claude AI through the Model Context Protocol (MCP), enabling sophisticated AI-assisted 3D modeling, procedural geometry creation, and persistent multi-turn workflows.

## ✨ **Enhanced Features**

### 🔄 **Shared Context & Persistence**
- **Persistent variables** between tool calls - no more isolated script execution
- **Object & material handles** for seamless cross-tool references
- **Operation history** tracking with automatic cleanup
- **Multi-turn conversations** that build on previous work

### 🔧 **Geometry Nodes Support**
- **AI-driven procedural modeling** with sophisticated geometry node networks
- **Blender 4.x compatibility** with automatic interface handling
- **Parametric object creation** (tables, chairs, organic shapes, complex geometry)
- **Auto-handle generation** for seamless tool chaining

### ⚡ **Advanced Tool Chaining**
- **13 new MCP tools** for context management and procedural modeling
- **Enhanced asset downloads** with automatic handle creation
- **Intelligent operation tracking** and debugging capabilities
- **Script registry system** for reusable Python code libraries

## 📦 **Installation (Enhanced Version)**

### From PyPI (Recommended)
```bash
uvx install blender-mcp-enhanced
```

### From Source
```bash
uvx install git+https://github.com/zachhandley/blender-mcp-enhanced.git
```

### For Development
```bash
git clone https://github.com/zachhandley/blender-mcp-enhanced.git
cd blender-mcp-enhanced
uvx install .
```


## 🙏 **Credits**

**Enhanced by:** [Zach Handley](https://github.com/zachhandley) ([zachhandley.com](https://zachhandley.com))
- Added shared context and persistent variables system
- Integrated comprehensive geometry nodes support
- Enhanced tool chaining and operation tracking

**Original Project:** Based on [BlenderMCP](https://github.com/ahujasid/blender-mcp) by the community

---

**Original Description:**

**We have no official website. Any website you see online is unofficial and has no affiliation with this project. Use them at your own risk.**

[Full tutorial](https://www.youtube.com/watch?v=lCyQ717DuzQ)

### Join the Community

Give feedback, get inspired, and build on top of the MCP: [Discord](https://discord.gg/z5apgR8TFU)

### Supporters

<div align="center" markdown="1">
   <sup>Special thanks to:</sup>
   <br>
   <br>
   <a href="https://www.warp.dev/blender-mcp">
      <img alt="Warp sponsorship" width="400" src="https://github.com/user-attachments/assets/c21102f7-bab9-4344-a731-0cf6b341cab2">
   </a>

### [Warp, the intelligent terminal for developers](https://www.warp.dev/blender-mcp)
[Available for MacOS, Linux, & Windows](https://www.warp.dev/blender-mcp)<br>

</div>
<hr>

**Other supporters:**

[CodeRabbit](https://www.coderabbit.ai/)

[Satish Goda](https://github.com/satishgoda)

**All supporters:**

[Support this project](https://github.com/sponsors/ahujasid)

## Release notes (1.2.0)
- View screenshots for Blender viewport to better understand the scene
- Search and download Sketchfab models


### Previously added features:
- Support for Poly Haven assets through their API
- Support to generate 3D models using Hyper3D Rodin
- For newcomers, you can go straight to Installation. For existing users, see the points below
- Download the latest addon.py file and replace the older one, then add it to Blender
- Delete the MCP server from Claude and add it back again, and you should be good to go!

## Features

- **Two-way communication**: Connect Claude AI to Blender through a socket-based server
- **Object manipulation**: Create, modify, and delete 3D objects in Blender
- **Material control**: Apply and modify materials and colors
- **Scene inspection**: Get detailed information about the current Blender scene
- **Code execution**: Run arbitrary Python code in Blender from Claude

## Components

The system consists of two main components:

1. **Blender Addon (`addon.py`)**: A Blender addon that creates a socket server within Blender to receive and execute commands
2. **MCP Server (`src/blender_mcp/server.py`)**: A Python server that implements the Model Context Protocol and connects to the Blender addon

## Installation


### Prerequisites

- Blender 3.0 or newer
- Python 3.10 or newer
- uv package manager: 

**If you're on Mac, please install uv as**
```bash
brew install uv
```
**On Windows**
```bash
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 
```
and then
```bash
set Path=C:\Users\nntra\.local\bin;%Path%
```

Otherwise installation instructions are on their website: [Install uv](https://docs.astral.sh/uv/getting-started/installation/)

**⚠️ Do not proceed before installing UV**

### Environment Variables

The following environment variables can be used to configure the Blender connection:

- `BLENDER_HOST`: Host address for Blender socket server (default: "localhost")
- `BLENDER_PORT`: Port number for Blender socket server (default: 9876)

Example:
```bash
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
```

### Claude for Desktop Integration

#### Quick Setup (Recommended)
Use the modern Claude CLI for the easiest setup:

```bash
claude mcp add blender uvx blender-mcp-enhanced
```

#### Manual Setup
[Watch the setup instruction video](https://www.youtube.com/watch?v=neoK_WMq92g) (Assuming you have already installed uv)

Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json to include the following:

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

### Cursor Integration

For Mac users, go to Settings > MCP and paste the following

- To use as a global server, use "add new global MCP server" button and paste
- To use as a project specific server, create `.cursor/mcp.json` in the root of the project and paste

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

For Windows users, go to Settings > MCP > Add Server, add a new server with the following settings:

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

[Cursor setup video](https://www.youtube.com/watch?v=wgWsJshecac)

**⚠️ Only run one instance of the MCP server at a time (Claude Desktop, Cursor, Codex, or VS Code), not multiple simultaneously**

### Codex Integration

For Codex users, you can add the MCP server using the CLI:

```bash
codex mcp add blender uvx blender-mcp-enhanced
```

Or manually configure in your Codex settings with:

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

### Visual Studio Code Integration

_Prerequisites_: Make sure you have [Visual Studio Code](https://code.visualstudio.com/) installed before proceeding.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_blender--mcp_server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22blender-mcp-enhanced%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22blender-mcp-enhanced%22%5D%7D)

### Installing the Blender Addon

1. Download the `addon.py` file from this repo
1. Open Blender
2. Go to Edit > Preferences > Add-ons
3. Click "Install..." and select the `addon.py` file
4. Enable the addon by checking the box next to "Interface: Blender MCP"


## Usage

### Starting the Connection
![BlenderMCP in the sidebar](assets/addon-instructions.png)

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Turn on the Poly Haven checkbox if you want assets from their API (optional)
4. Click "Connect to Claude"
5. Make sure the MCP server is running in your terminal

### Using with Claude

Once the config file has been set on Claude, and the addon is running on Blender, you will see a hammer icon with tools for the Blender MCP.

![BlenderMCP in the sidebar](assets/hammer-icon.png)

#### Capabilities

- Get scene and object information 
- Create, delete and modify shapes
- Apply or create materials for objects
- Execute any Python code in Blender
- Download the right models, assets and HDRIs through [Poly Haven](https://polyhaven.com/)
- AI generated 3D models through [Hyper3D Rodin](https://hyper3d.ai/)


### Example Commands

Here are some examples of what you can ask Claude to do:

- "Create a low poly scene in a dungeon, with a dragon guarding a pot of gold" [Demo](https://www.youtube.com/watch?v=DqgKuLYUv00)
- "Create a beach vibe using HDRIs, textures, and models like rocks and vegetation from Poly Haven" [Demo](https://www.youtube.com/watch?v=I29rn92gkC4)
- Give a reference image, and create a Blender scene out of it [Demo](https://www.youtube.com/watch?v=FDRb03XPiRo)
- "Generate a 3D model of a garden gnome through Hyper3D"
- "Get information about the current scene, and make a threejs sketch from it" [Demo](https://www.youtube.com/watch?v=jxbNI5L7AH8)
- "Make this car red and metallic" 
- "Create a sphere and place it above the cube"
- "Make the lighting like a studio"
- "Point the camera at the scene, and make it isometric"

### 🚀 **Enhanced Examples (New in this Fork)**

#### **Persistent Multi-Turn Workflows**
- "Create a cube, store it as 'my_cube', then in the next prompt scale it by 2"
- "Download a wood texture, save the material handle, then apply it to all selected objects"
- "Create 5 different objects, store them all, then arrange them in a circle using their handles"

#### **Geometry Nodes Procedural Modeling**
- "Create a simple procedural table using geometry nodes"
- "Use geometry nodes to create a parametric chair with exposed height and width controls"
- "Generate a noise-deformed sphere with geometry nodes and exposed strength parameter"
- "Create points distributed on a sphere surface with controllable density"
- "Build a procedural car using geometry node networks"

#### **Script Registry System**
- "Register a lighting setup script for reuse across projects"
- "Create and store utility scripts for material creation, then execute them when needed"
- "Build a library of geometry node templates and execute them by name"
- "Store scene analysis scripts in different categories and run them on-demand"

#### **Advanced Tool Chaining**
- "Download a Poly Haven texture, create a procedural object with geometry nodes, and apply the texture"
- "Generate multiple objects with Hyper3D, store their handles, then create a scene composition"
- "Create a procedural building, get its dimensions, then create matching furniture to scale"

## Hyper3D integration

Hyper3D's free trial key allows you to generate a limited number of models per day. If the daily limit is reached, you can wait for the next day's reset or obtain your own key from hyper3d.ai and fal.ai.

## Troubleshooting

- **Connection issues**: Make sure the Blender addon server is running, and the MCP server is configured on Claude, DO NOT run the uvx command in the terminal. Sometimes, the first command won't go through but after that it starts working.
- **Timeout errors**: Try simplifying your requests or breaking them into smaller steps
- **Poly Haven integration**: Claude is sometimes erratic with its behaviour
- **Have you tried turning it off and on again?**: If you're still having connection errors, try restarting both Claude and the Blender server


## Technical Details

### Communication Protocol

The system uses a simple JSON-based protocol over TCP sockets:

- **Commands** are sent as JSON objects with a `type` and optional `params`
- **Responses** are JSON objects with a `status` and `result` or `message`

## Limitations & Security Considerations

- The `execute_blender_code` tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments. ALWAYS save your work before using it.
- Poly Haven requires downloading models, textures, and HDRI images. If you do not want to use it, please turn it off in the checkbox in Blender. 
- Complex operations might need to be broken down into smaller steps


## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This is a third-party integration and not made by Blender. Made by [Siddharth](https://x.com/sidahuj)