blender-mcp 1.0.0

Blender integration through the Model Context Protocol

BlenderMCP - Blender Model Context Protocol Integration

BlenderMCP connects Blender to Claude AI through the Model Context Protocol (MCP), allowing Claude to directly interact with and control Blender. This integration enables AI-assisted 3D modeling, scene manipulation, and rendering.

Features

• Two-way communication: Connect Claude AI to Blender through a socket-based server
• Object manipulation: Create, modify, and delete 3D objects in Blender
• Material control: Apply and modify materials and colors
• Scene inspection: Get detailed information about the current Blender scene
• Code execution: Run arbitrary Python code in Blender from Claude

Components

The system consists of two main components:

1. Blender Addon (blender_mcp_addon.py): A Blender addon that creates a socket server within Blender to receive and execute commands
2. MCP Server (blender_mcp_server.py): A Python server that implements the Model Context Protocol and connects to the Blender addon

Installation

Prerequisites

• Blender 3.0 or newer
• Python 3.7 or newer
• MCP library (pip install mcp)

Quick Start

Run blender-mcp without installing it permanently (pipx will automatically download and run the package):

pipx run blender-mcp

If you don't have pipx installed, you can install it with:

python -m pip install pipx

Claude for Desktop Integration

Update your claude_desktop_config.json (located in ~/Library/Application\ Support/Claude/claude_desktop_config.json on macOS and %APPDATA%/Claude/claude_desktop_config.json on Windows) to include the following:

{
    "mcpServers": {
        "blender": {
            "command": "pipx",
            "args": [
                "run",
                "blender-mcp"
            ]
        }
    }
}

This configuration allows Claude for Desktop to automatically start the Blender MCP server when needed. The pipx command will handle both downloading and running the package in one step.

Installing the Blender Addon

1. Open Blender
2. Go to Edit > Preferences > Add-ons
3. Click "Install..." and select the blender_mcp_addon.py file
4. Enable the addon by checking the box next to "Interface: Blender MCP"

Setting up the MCP Server

1. Install the required Python packages:

   pip install mcp
   

2. Run the MCP server:

   python blender_mcp_server.py
   

Usage

Starting the Connection

1. In Blender, go to the 3D View sidebar (press N if not visible)
2. Find the "BlenderMCP" tab
3. Set the port number (default: 9876)
4. Click "Start MCP Server"
5. Make sure the MCP server is running in your terminal

Using with Claude

Once connected, Claude can interact with Blender using the following capabilities:

Resources

• blender://ping - Check connectivity
• blender://simple - Get basic Blender information
• blender://scene - Get detailed scene information
• blender://object/{object_name} - Get information about a specific object

Tools

• create_primitive - Create basic primitive objects with optional color
• set_object_property - Set a single property of an object
• create_object - Create a new object with detailed parameters
• modify_object - Modify an existing object's properties
• delete_object - Remove an object from the scene
• set_material - Apply or create materials for objects
• execute_blender_code - Run arbitrary Python code in Blender

Example Commands

Here are some examples of what you can ask Claude to do:

• "Create a blue cube at position [0, 1, 0]"
• "Make the cube red"
• "Create a sphere and place it above the cube"
• "Get information about the current scene"
• "Delete the cube"

Troubleshooting

• Connection issues: Make sure both the Blender addon server and the MCP server are running
• Command failures: Check the console in Blender for error messages
• Timeout errors: Try simplifying your requests or breaking them into smaller steps

Technical Details

Communication Protocol

The system uses a simple JSON-based protocol over TCP sockets:

• Commands are sent as JSON objects with a type and optional params
• Responses are JSON objects with a status and result or message

Security Considerations

The execute_blender_code tool allows running arbitrary Python code in Blender, which can be powerful but potentially dangerous. Use with caution in production environments.

Limitations

• The connection is local only (localhost)
• Large data transfers may cause timeouts
• Complex operations might need to be broken down into smaller steps

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

[Your license information here]