# BlenderMCP - Blender Model Context Protocol Integration

BlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender. This integration enables AI-assisted 3D modeling, scene manipulation, and rendering.

## 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 (`blender_mcp_addon.py`)**: A Blender addon that creates a socket server within Blender to receive and execute commands
2. **MCP Server (`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.7 or newer
- MCP library (`pip install mcp`)

### Quick Start

Run blender-mcp without installing it permanently (pipx or uvx will automatically download and run the package):

```bash
pipx run blender-mcp
```

If you don't have p installed, you can run it with uv:

```bash
uvx run blender-mcp
```


If you don't have either, download uv:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### Claude for Desktop Integration

Update your `claude_desktop_config.json` (located in `~/Library/Application\ Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%/Claude/claude_desktop_config.json` on Windows) to include the following:

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

This configuration allows Claude for Desktop to automatically start the Blender MCP server when needed. The pipx command will handle both downloading and running the package in one step.

### 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

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Set the port number (default: 9876)
4. Click "Start MCP Server"
5. Make sure the MCP server is running in your terminal

### Using with Claude

Once connected, Claude can interact with Blender using the following capabilities:

#### Tools

- `get_scene_info` - Gets scene information
- `get_object_info` - Gets detailed information for a specific object in the scene
- `create_primitive` - Create basic primitive objects with optional color
- `set_object_property` - Set a single property of an object
- `create_object` - Create a new object with detailed parameters
- `modify_object` - Modify an existing object's properties
- `delete_object` - Remove an object from the scene
- `set_material` - Apply or create materials for objects
- `execute_blender_code` - Run any Python code in Blender

### 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"
- "Make the car red and metallic"
- "Create a sphere and place it above the cube"
- "Get information about the current scene, and make a threejs sketch from it"
- "Make the lighting like a studio"
- "Point the camera at the scene, and make it isometric"

## Troubleshooting

- **Connection issues**: Make sure both the Blender addon server and the MCP server are running
- **Command failures**: Check the console in Blender for error messages
- **Timeout errors**: Try simplifying your requests or breaking them into smaller steps

## 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`

### 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.

## Limitations

- The connection is local only (localhost)
- Large data transfers may cause timeouts
- Complex operations might need to be broken down into smaller steps

## Contributing

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