# Blender MCP Server - AI-Powered 3D Generation

A comprehensive Model Context Protocol (MCP) server that enables AI-powered 3D content creation in Blender through natural language. Built for seamless integration with Claude and other MCP-compatible AI assistants.

## Features

### Core Capabilities
- **Text-to-3D Generation**: Describe what you want in words, get 3D models
- **Image-to-3D**: Upload reference images and generate matching 3D geometry
- **Animation System**: Create rotations, bounces, and custom animations
- **Auto-Rigging**: Automatic armature generation for characters and objects
- **Rendering**: High-quality renders with configurable settings
- **Export**: Support for FBX, OBJ, GLTF, STL, and USD formats

### Integration Features
- **Context7 MCP**: Access to up-to-date Blender API documentation
- **Playwright MCP**: Automated testing and validation
- **Vision Models**: Image analysis for reference-based generation
- **Claude Integration**: Optimized for Claude AI workflows

## Installation

### Prerequisites
- Python 3.11 or higher
- Blender 4.5 or higher (tested with 4.5.3 LTS)
- Node.js (for Context7 and Playwright MCPs)

### Quick Start

1. **Clone or download this repository**:
   ```bash
   cd blender-mcp-server
   ```

2. **Install Python dependencies**:
   ```bash
   pip install -e .
   ```

3. **Configure Blender path** (if not default):
   Edit `src/server.py` and update:
   ```python
   BLENDER_PATH = r"C:\Program Files\Blender Foundation\Blender 4.5\blender.exe"
   ```

4. **Test the server**:
   ```bash
   python src/server.py
   ```

## Usage

### Configure in Claude Desktop

Add to your Claude Desktop MCP configuration (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\blender-mcp-server\\src\\server.py"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}
```

### Example Prompts

**Text-to-3D**:
```
Use the blender server to create a low-poly spaceship with sleek design
```

**Image-to-3D**:
```
Generate a 3D model based on this reference image: C:\images\chair.jpg
```

**Animation**:
```
Create a rotating animation for the spaceship object, 240 frames
```

**Rigging**:
```
Add humanoid rigging to the character model
```

**Export**:
```
Export the spaceship as FBX to C:\exports\spaceship.fbx
```

## Available Tools

### generate_3d_from_text
Generate 3D objects from natural language descriptions.

**Parameters**:
- `description` (required): Detailed description of the 3D object
- `style`: Style hints (realistic, lowpoly, stylized, cartoonish)
- `output_name`: Output filename
- `render`: Whether to render the object (default: true)

**Example**:
```json
{
  "description": "A futuristic hover car with neon lights",
  "style": "lowpoly",
  "output_name": "hover_car",
  "render": true
}
```

### generate_3d_from_image
Generate 3D objects from reference images.

**Parameters**:
- `image_path` (required): Path to reference image
- `description`: Additional clarifications
- `output_name`: Output filename

### create_animation
Create animations for 3D objects.

**Parameters**:
- `object_name` (required): Name of object to animate
- `animation_type` (required): rotate, bounce, walk, custom
- `duration`: Animation length in frames (default: 120)
- `parameters`: Animation-specific settings

### add_rigging
Add armature/bones to models for animation.

**Parameters**:
- `object_name` (required): Name of object to rig
- `rig_type` (required): humanoid, animal, mechanical, custom

### render_scene
Render the current scene to image or animation.

**Parameters**:
- `output_path` (required): Output file path
- `resolution`: [width, height] (default: [1920, 1080])
- `samples`: Render quality (default: 128)
- `animation`: Render as animation (default: false)

### export_model
Export 3D models to various formats.

**Parameters**:
- `object_name` (required): Name of object to export
- `output_path` (required): Output file path with extension
- `format`: FBX, OBJ, GLTF, STL, USD (default: FBX)

### list_objects
List all objects in the current Blender scene.

### get_scene_info
Get detailed information about the current scene.

## Testing

### Manual Testing

Test individual tools directly:

```bash
# Test text-to-3D generation
python -c "
import asyncio
from src.server import BlenderMCPServer, Text3DRequest

async def test():
    server = BlenderMCPServer()
    request = Text3DRequest(description='a simple cube', output_name='test_cube')
    result = await server.generate_3d_from_text(request)
    print(result)

asyncio.run(test())
"
```

### Automated Testing with Playwright MCP

The server includes integration with Playwright MCP for end-to-end automated testing. Tests verify:
- Tool registration and availability
- Text-to-3D generation pipeline
- Image analysis and processing
- Animation creation
- Export functionality
- Error handling

Run tests:
```bash
pytest tests/ -v
```

## Architecture

```
blender-mcp-server/
├── src/
│   ├── __init__.py          # Package initialization
│   └── server.py            # Main MCP server implementation
├── tests/
│   ├── test_server.py       # Unit tests
│   └── test_integration.py  # Integration tests with Playwright
├── examples/
│   ├── basic_usage.py       # Basic examples
│   └── advanced_usage.py    # Advanced workflows
├── pyproject.toml           # Project configuration
└── README.md                # This file
```

## Advanced Usage

### Custom Geometry Generation

The server uses AI to interpret descriptions and generate appropriate geometry. You can enhance generation by:

1. **Detailed Descriptions**: "A medieval castle with four towers, stone walls, and a wooden drawbridge"
2. **Style Hints**: "realistic", "lowpoly", "stylized", "cartoonish"
3. **Material Descriptions**: Include color, texture, and material properties

### Image Reference Learning

The image-to-3D feature uses vision models to analyze reference images:

```python
# In your prompts
"Create a 3D model matching this concept art: path/to/image.jpg
Focus on the overall form and proportions"
```

### Complex Animations

Create sophisticated animations by chaining tools:

```python
# 1. Generate object
"Create a robotic arm"

# 2. Add rigging
"Add mechanical rigging to the robotic arm"

# 3. Animate
"Create a custom animation where the arm reaches forward and grabs"
```

## Configuration

### Environment Variables

- `BLENDER_PATH`: Path to Blender executable
- `BLENDER_OUTPUT_DIR`: Output directory for generated files
- `ANTHROPIC_API_KEY`: API key for Claude integration

### Blender Settings

Configure in `src/server.py`:

```python
class BlenderConfig:
    blender_path: str = "C:\\Program Files\\Blender Foundation\\Blender 4.5\\blender.exe"
    output_dir: Path = Path(tempfile.gettempdir()) / "blender_mcp_output"
    default_resolution: tuple[int, int] = (1920, 1080)
    default_samples: int = 128
```

## Troubleshooting

### Server Won't Start
- Verify Blender path in `src/server.py`
- Check Python version (3.11+)
- Ensure all dependencies installed: `pip install -e .`

### Generation Fails
- Check Blender installation
- Verify output directory permissions
- Review logs in console output

### Render Quality Issues
- Increase sample count in render settings
- Use higher resolution
- Check lighting setup in generated scenes

## Performance Tips

1. **Batch Operations**: Generate multiple objects before rendering
2. **Resolution**: Use lower resolution for previews, higher for finals
3. **Samples**: 64 samples for preview, 256+ for final renders
4. **Background Mode**: Blender runs in background for faster processing

## Integration with Other MCPs

### Context7
Get Blender API documentation:
```
Ask context7 about Blender Python API for creating materials
```

### Playwright
Automated testing:
```
Use playwright to test the blender generation workflow
```

## Contributing

Contributions are welcome! Areas for improvement:
- Enhanced geometry generation algorithms
- More animation presets
- Better material and texture systems
- Advanced rigging templates
- Integration with more AI models

## License

MIT License - See LICENSE file for details

## Acknowledgments

- Built with [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- Blender API documentation
- Anthropic Claude for AI integration
- Context7 and Playwright MCP servers

## Support

For issues and questions:
1. Check the troubleshooting section
2. Review Blender logs in output directory
3. Verify MCP configuration in Claude Desktop
4. Test individual tools manually

## Roadmap

- [ ] Advanced material system with PBR textures
- [ ] Physics simulations
- [ ] Particle systems
- [ ] More rigging presets (quadruped, vehicle, etc.)
- [ ] Real-time preview with Blender viewport
- [ ] Integration with Stable Diffusion for textures
- [ ] Support for Blender add-ons
- [ ] Multi-object scene composition
- [ ] Version control for 3D assets

---

**Made with Claude Code** - Demonstrating the power of MCP for creative applications