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:

   cd blender-mcp-server
   

2. Install Python dependencies:

   pip install -e .
   

3. Configure Blender path (if not default): Edit src/server.py and update:

   BLENDER_PATH = r"C:\Program Files\Blender Foundation\Blender 4.5\blender.exe"
   

4. Test the server:

   python src/server.py
   

Usage

Configure in Claude Desktop

Add to your Claude Desktop MCP configuration (%APPDATA%\Claude\claude_desktop_config.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:

{
  "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:

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

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:

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

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

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