blender_mcp_server

3Dean/blender_mcp_server

3.1

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

The Blender MCP Server is a Model Context Protocol server that enables automation and rendering capabilities in Blender 3D through programmatic control.

Tools
6
Resources
0
Prompts
0

Blender MCP Server

A Model Context Protocol (MCP) server that provides powerful Blender 3D automation and rendering capabilities. This server allows you to control Blender programmatically through MCP tools, enabling automated rendering, scene creation, Python script execution, and more.

Features

🎬 Rendering Tools

  • render_scene: Render Blender scenes to images or animations
  • batch_render: Render multiple Blender files efficiently
  • Support for various output formats (PNG, JPEG, EXR, TIFF, BMP)
  • Customizable resolution and sampling settings

🎨 Scene Management

  • create_scene: Generate new Blender scenes with predefined setups
  • get_scene_info: Analyze existing Blender files
  • Multiple scene types: basic, studio_lighting, outdoor, product_showcase
  • Automatic object placement and lighting setup

🐍 Python Integration

  • execute_python_script: Run Python scripts inside Blender
  • Full access to Blender's Python API (bpy)
  • Ability to modify and save scenes programmatically

🔧 Addon Management

  • install_addon: Install and enable Blender addons
  • Support for both .py and .zip addon files

Installation

  1. Install Dependencies

    npm install

  2. Build the Server

    npm run build

  3. Configure Blender Path (Optional) Set environment variables for custom Blender installation:

    export BLENDER_PATH="/path/to/blender"
export BLENDER_OUTPUT_PATH="/path/to/renders"

Usage

Starting the Server

npm start

The server runs on stdio and can be integrated with MCP-compatible clients.

Configuration

The server accepts the following environment variables:

  • BLENDER_PATH: Path to Blender executable (default: "blender")
  • BLENDER_OUTPUT_PATH: Default output directory for renders (default: "./renders")

MCP Client Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": ["path/to/blender-mcp-server/build/index.js"]
    }
  }
}

Available Tools

render_scene

Render a Blender scene to an image or animation.

Parameters:

  • blendFile (required): Path to the .blend file
  • outputPath (optional): Output path for rendered files
  • format (optional): Output format (PNG, JPEG, EXR, TIFF, BMP)
  • frame (optional): Specific frame to render
  • resolution (optional): Render resolution {x, y}
  • samples (optional): Number of samples for rendering

Example:

{
  "blendFile": "./scenes/my_scene.blend",
  "outputPath": "./renders/output",
  "format": "PNG",
  "resolution": {"x": 1920, "y": 1080},
  "samples": 128
}

execute_python_script

Execute a Python script inside Blender.

Parameters:

  • script (required): Python script to execute
  • blendFile (optional): .blend file to load
  • saveFile (optional): Path to save modified file

Example:

{
  "script": "import bpy; bpy.ops.mesh.primitive_cube_add(location=(0, 0, 2))",
  "blendFile": "./scenes/base.blend",
  "saveFile": "./scenes/modified.blend"
}

create_scene

Create a new Blender scene with basic objects.

Parameters:

  • outputFile (required): Path to save the new .blend file
  • sceneType (optional): Type of scene (basic, studio_lighting, outdoor, product_showcase)
  • objects (optional): Array of objects to add

Example:

{
  "outputFile": "./scenes/new_scene.blend",
  "sceneType": "studio_lighting",
  "objects": [
    {
      "type": "sphere",
      "location": [0, 0, 1],
      "scale": [1.5, 1.5, 1.5],
      "material": "RedMaterial"
    }
  ]
}

get_scene_info

Get detailed information about a Blender scene.

Parameters:

  • blendFile (required): Path to the .blend file to analyze

Example:

{
  "blendFile": "./scenes/my_scene.blend"
}

batch_render

Render multiple Blender files or frames.

Parameters:

  • blendFiles (required): Array of .blend file paths
  • outputDir (required): Directory to save rendered files
  • format (optional): Output format for all renders
  • frameRange (optional): Frame range {start, end}

Example:

{
  "blendFiles": ["./scene1.blend", "./scene2.blend"],
  "outputDir": "./batch_renders",
  "format": "PNG"
}

install_addon

Install a Blender addon.

Parameters:

  • addonPath (required): Path to addon file (.py or .zip)
  • enable (optional): Whether to enable after installation (default: true)

Example:

{
  "addonPath": "./addons/my_addon.py",
  "enable": true
}

Scene Types

Basic

  • Simple sun light
  • Basic camera positioning
  • Minimal setup for quick prototyping

Studio Lighting

  • Professional 3-point lighting setup
  • Area lights for soft shadows
  • Optimized for product visualization

Outdoor

  • Sun light with high energy
  • Ground plane
  • Natural lighting simulation

Product Showcase

  • Key, fill, and rim lighting
  • Professional backdrop
  • Optimized for product photography

Object Types

Supported primitive objects:

  • cube: Basic cube primitive
  • sphere: UV sphere
  • cylinder: Cylinder primitive
  • plane: Flat plane
  • monkey: Suzanne (Blender's mascot)

Each object supports:

  • Custom location [x, y, z]
  • Custom scale [x, y, z]
  • Material assignment

Error Handling

The server provides comprehensive error handling:

  • File existence validation
  • Blender process monitoring
  • Detailed error messages
  • Graceful failure recovery

Requirements

  • Blender: Version 2.8+ (3.0+ recommended)
  • Node.js: Version 16+
  • Operating System: Windows, macOS, or Linux

Development

Building from Source

git clone <repository>
cd blender-mcp-server
npm install
npm run build

Development Mode

npm run dev

This starts TypeScript in watch mode for development.

Troubleshooting

Common Issues

  1. Blender not found

    • Ensure Blender is in your PATH or set BLENDER_PATH environment variable
    • Test with: blender --version

  2. Permission errors

    • Ensure write permissions for output directories
    • Check file permissions for .blend files

  3. Render failures

    • Verify .blend file is not corrupted
    • Check available disk space
    • Ensure proper scene setup (camera, lighting)

Debug Mode

Set environment variable for verbose output:

DEBUG=1 npm start

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

Note: This MCP server requires Blender to be installed on your system. The server communicates with Blender through command-line interface and Python scripting.