# Blender MCP (Model Context Protocol)

A Blender addon that enables AI assistants (like Claude) to interact with Blender through the Model Context Protocol (MCP).

## Installation

### 1. Install the Blender Addon

1. Download or clone this repository
2. Copy the entire `src/blender_mcp/addon/` directory to your Blender addons folder:
   - **Windows**: `%APPDATA%\Blender Foundation\Blender\4.x\scripts\addons\`
   - **macOS**: `~/Library/Application Support/Blender/4.x/scripts/addons/`
   - **Linux**: `~/.config/blender/4.x/scripts/addons/`

3. Rename the copied directory from `addon` to `blender_mcp`

4. Open Blender and go to `Edit > Preferences > Add-ons`
5. Search for "Blender MCP" and enable the addon

### 2. Install the MCP Server

The MCP server runs outside Blender and communicates with it via sockets.

1. Install Python dependencies:
   ```bash
   pip install mcp-server-fastmcp
   ```

2. Or if using the provided virtual environment:
   ```bash
   # Activate the virtual environment
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

   # Install dependencies
   pip install -r requirements.txt
   ```

### 3. Configure Your MCP Client

Add the Blender MCP server to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_mcp.server"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}
```

## Usage

1. **Start Blender** and enable the Blender MCP addon
2. **Start your MCP client** (Claude Desktop, etc.) with the server configured
3. **In Blender**, click the "Connect to MCP server" button in the BlenderMCP panel (N-panel > BlenderMCP)
4. **Use Claude** to interact with Blender through natural language commands

## Features

### Core Tools
- **Scene Information**: Get details about objects, materials, and scene structure
- **Object Manipulation**: Query and modify 3D objects
- **Viewport Screenshots**: Capture Blender's 3D viewport
- **Code Execution**: Run Python code directly in Blender

### Template Engine
- **Template Management**: Create, save, and reuse complex operations
- **Dynamic Overrides**: Apply templates with parameter modifications
- **Template Search**: Discover templates by tags and categories
- **Usage Analytics**: Track template performance and success rates
- **Version Control**: Optional Git versioning for template evolution

### Asset Integrations
- **PolyHaven**: Download HDRIs, textures, and 3D models
- **Sketchfab**: Search and download 3D models
- **Hyper3D Rodin**: Generate 3D models from text or images

## Configuration

### Blender Addon Settings
- **Port**: Socket port for communication (default: 9876)
- **PolyHaven**: Enable/disable PolyHaven integration
- **Hyper3D**: Configure API keys and modes
- **Sketchfab**: Configure API key for model downloads

### Environment Variables
- `BLENDER_HOST`: Host address (default: localhost)
- `BLENDER_PORT`: Port number (default: 9876)

## Architecture

The system consists of two main components:

1. **Blender Addon** (`src/blender_mcp/addon/`): Runs inside Blender, handles UI and executes Blender operations
2. **MCP Server** (`src/blender_mcp/server/`): Runs outside Blender, provides MCP tools and manages communication

## Development

### Project Structure
```
src/blender_mcp/
├── addon/              # Blender addon code
│   ├── handlers.py     # Base command handlers
│   ├── polyhaven_handlers.py  # PolyHaven integration
│   ├── hyper3d_handlers.py    # Hyper3D integration
│   ├── sketchfab_handlers.py  # Sketchfab integration
│   ├── ui.py           # Blender UI components
│   ├── server.py       # Socket server for addon
│   └── __main__.py     # Addon registration
└── server/             # MCP server code
    ├── connection.py   # MCP server and socket client
    ├── tools.py        # Core Blender tools
    ├── integrations.py # Integration tools
    ├── template_engine.py     # Template storage and management
    ├── template_tools.py      # MCP tools for templates
    ├── prompts.py      # MCP prompts
    └── __main__.py     # Server entry point
templates/              # Template storage directory
├── template_name.json  # Template definitions
└── analytics.json      # Usage statistics
```

### Running Tests
```bash
# Test server modules
python -m pytest tests/

# Or manually test imports
python -c "from src.blender_mcp.server.connection import mcp; print('OK')"
```

## Troubleshooting

### Connection Issues
- Ensure the Blender addon is enabled and running
- Check that the port numbers match between client and server
- Verify firewall settings allow socket connections

### Integration Issues
- Check API keys are properly configured in Blender
- Ensure internet connectivity for external services
- Review Blender console for error messages

### Performance
- Large scenes may take time to process
- Asset downloads depend on internet speed
- 3D generation can take several minutes

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

See LICENSE file for details.