120 lines
3.9 KiB
Markdown
120 lines
3.9 KiB
Markdown
# 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
|
|
- **Rendering**: Trigger renders directly 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`)
|
|
|
|
### 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]
|