che-blender-mcp

che-blender-mcp

   

Blender MCP Server - Execute scripts, capture renders, and control 3D scenes via Claude.

---

Features

• 6 tools for comprehensive Blender control
• Execute arbitrary Python code with full bpy access
• Render scenes and return images directly to Claude
• Supports Cycles & EEVEE render engines
• Zero GUI required - runs Blender in background mode

---

Quick Start

For Claude Code (CLI)

# Clone and install
git clone https://github.com/kiki830621/che-blender-mcp.git
cd che-blender-mcp
pip install -e .

# Add to Claude Code
claude mcp add che-blender-mcp -- python3 -m che_blender_mcp

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-blender-mcp": {
      "command": "python3",
      "args": ["-m", "che_blender_mcp"],
      "env": {
        "BLENDER_PATH": "/Applications/Blender.app/Contents/MacOS/Blender"
      }
    }
  }
}

---

Configuration

Blender Path

By default, the server looks for Blender at: `` /Applications/Blender.app/Contents/MacOS/Blender ``

To use a different path, set the BLENDER_PATH environment variable:

Claude Code: ``bash claude mcp add che-blender-mcp \ --env BLENDER_PATH=/path/to/blender \ -- python3 -m che_blender_mcp ``

Claude Desktop: ``json { "mcpServers": { "che-blender-mcp": { "command": "python3", "args": ["-m", "che_blender_mcp"], "env": { "BLENDER_PATH": "/path/to/blender" } } } } ``

---

All 6 Tools

| Tool | Description | |------|-------------| | execute_script | Execute arbitrary Python code in Blender with full bpy access | | list_objects | List all scene objects with name, type, location, visibility | | get_object_info | Get detailed info: mesh vertices/faces, light energy/color, camera lens | | render | Render scene and return base64-encoded PNG image | | get_scene_info | Get cameras, lights, render settings, frame range | | screenshot | Capture a viewport screenshot (renders at 50% resolution for speed) |

---

Tool Parameters

execute_script

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | script | string | ✅ | Python code to execute | | blend_file | string | | Path to .blend file to open first |

list_objects

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | blend_file | string | | Path to .blend file to open | | object_type | string | | Filter: MESH, CAMERA, LIGHT, EMPTY, ARMATURE |

get_object_info

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | object_name | string | ✅ | Name of the object to inspect | | blend_file | string | | Path to .blend file to open |

render

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | blend_file | string | ✅ | Path to .blend file to render | | resolution_x | integer | | Width in pixels (default: 1920) | | resolution_y | integer | | Height in pixels (default: 1080) | | samples | integer | | Cycles samples (default: 128) | | engine | string | | CYCLES or BLENDER_EEVEE_NEXT (default: CYCLES) |

get_scene_info

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | blend_file | string | | Path to .blend file to open |

screenshot

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | blend_file | string | ✅ | Path to .blend file | | view | string | | CAMERA, TOP, FRONT, RIGHT (default: CAMERA) |

---

Usage Examples

"Open my_scene.blend and list all objects"
"Render /path/to/scene.blend at 1080p with 256 samples"
"Execute this script in Blender: bpy.ops.mesh.primitive_cube_add()"
"Get info about the object named 'Camera'"
"Show me the scene information for my project"

Example: Create and Render a Scene

"Execute this script:
import bpy
bpy.ops.mesh.primitive_monkey_add(location=(0, 0, 0))
bpy.ops.object.shade_smooth()
"

"Now render the scene at 720p"

---

Requirements

• macOS 13.0 (Ventura) or later
• Blender 4.0+ (recommended: Blender 5.0)
• Python 3.10+

---

Privacy

This extension:

• Runs entirely locally on your Mac
• Does not transmit any data externally
• Only accesses local Blender installation and specified blend files
• See PRIVACY.md for full details

---

Version History

| Version | Changes | |---------|---------| | v0.1.0 | Initial release with 6 tools: execute_script, list_objects, get_object_info, render, get_scene_info, screenshot |

---

Related Projects

• che-things-mcp - MCP server for Things 3 task management
• che-ical-mcp - MCP server for macOS Calendar & Reminders

---

License

MIT

Author

Che Cheng