blender-mcp-enhanced

dorialn68/blender-mcp-enhanced

3.2

If you are the rightful owner of blender-mcp-enhanced and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Blender MCP Server is an AI-powered platform for 3D content creation in Blender using natural language.

Tools
8
Resources
0
Prompts
0

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