https://github.com/dhakalnirajan/blender-open-mcp
https://github.com/dhakalnirajan/blender-open-mcp
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/dhakalnirajan/blender-open-mcp
- Owner: dhakalnirajan
- License: other
- Created: 2025-03-14T09:58:21.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-03-14T10:45:44.000Z (2 months ago)
- Last Synced: 2025-03-14T11:29:28.350Z (2 months ago)
- Language: Python
- Size: 52.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# blender-open-mcp
`blender-open-mcp` is an open source project that integrates Blender with local AI models (via [Ollama](https://ollama.com/)) using the Model Context Protocol (MCP). This allows you to control Blender using natural language prompts, leveraging the power of AI to assist with 3D modeling tasks.
## Features
- **Control Blender with Natural Language:** Send prompts to a locally running Ollama model to perform actions in Blender.
- **MCP Integration:** Uses the Model Context Protocol for structured communication between the AI model and Blender.
- **Ollama Support:** Designed to work with Ollama for easy local model management.
- **Blender Add-on:** Includes a Blender add-on to provide a user interface and handle communication with the server.
- **PolyHaven Integration (Optional):** Download and use assets (HDRIs, textures, models) from [PolyHaven](https://polyhaven.com/) directly within Blender via AI prompts.
- **Basic 3D Operations:**
- Get Scene and Object Info
- Create Primitives
- Modify and delete objects
- Apply materials
- **Render Support:** Render images using the tool and retrieve information based on the output.
## Installation
### Prerequisites
1. **Blender:** Blender 3.0 or later. Download from [blender.org](https://www.blender.org/download/).
2. **Ollama:** Install from [ollama.com](https://ollama.com/), following OS-specific instructions.
3. **Python:** Python 3.10 or later.
4. **uv:** Install using `pip install uv`.
5. **Git:** Required for cloning the repository.
### Installation Steps
1. **Clone the Repository:**
```bash
git clone https://github.com/dhakalnirajan/blender-open-mcp.git
cd blender-open-mcp
```
2. **Create and Activate a Virtual Environment (Recommended):**
```bash
uv venv
source .venv/bin/activate # On Linux/macOS
.venv\Scripts\activate # On Windows
```
3. **Install Dependencies:**
```bash
uv pip install -e .
```
4. **Install the Blender Add-on:**
- Open Blender.
- Go to `Edit -> Preferences -> Add-ons`.
- Click `Install...`.
- Select the `addon.py` file from the `blender-open-mcp` directory.
- Enable the "Blender MCP" add-on.
5. **Download an Ollama Model (if not already installed):**
```bash
ollama pull ollama run llama3.2
```
*(Other models like **`Gemma3`** can also be used.)*
## Setup
1. **Start the Ollama Server:** Ensure Ollama is running in the background.
2. **Start the MCP Server:**
```bash
blender-mcp
```
Or,
```bash
python src/blender_open_mcp/server.py
```
By default, it listens on `http://0.0.0.0:8000`, but you can modify settings:
```bash
blender-mcp --host 127.0.0.1 --port 8001 --ollama-url http://localhost:11434 --ollama-model llama3.2
```
3. **Start the Blender Add-on Server:**
- Open Blender and the 3D Viewport.
- Press `N` to open the sidebar.
- Find the "Blender MCP" panel.
- Click "Start MCP Server".
## Usage
Interact with `blender-open-mcp` using the `mcp` command-line tool:
### Example Commands
- **Basic Prompt:**
```bash
mcp prompt "Hello BlenderMCP!" --host http://localhost:8000
```
- **Get Scene Information:**
```bash
mcp tool get_scene_info --host http://localhost:8000
```
- **Create a Cube:**
```bash
mcp prompt "Create a cube named 'my_cube'." --host http://localhost:8000
```
- **Render an Image:**
```bash
mcp prompt "Render the image." --host http://localhost:8000
```
- **Using PolyHaven (if enabled):**
```bash
mcp prompt "Download a texture from PolyHaven." --host http://localhost:8000
```
## Available Tools
| Tool Name | Description | Parameters |
| -------------------------- | -------------------------------------- | ----------------------------------------------------- |
| `get_scene_info` | Retrieves scene details. | None |
| `get_object_info` | Retrieves information about an object. | `object_name` (str) |
| `create_object` | Creates a 3D object. | `type`, `name`, `location`, `rotation`, `scale` |
| `modify_object` | Modifies an object’s properties. | `name`, `location`, `rotation`, `scale`, `visible` |
| `delete_object` | Deletes an object. | `name` (str) |
| `set_material` | Assigns a material to an object. | `object_name`, `material_name`, `color` |
| `render_image` | Renders an image. | `file_path` (str) |
| `execute_blender_code` | Executes Python code in Blender. | `code` (str) |
| `get_polyhaven_categories` | Lists PolyHaven asset categories. | `asset_type` (str) |
| `search_polyhaven_assets` | Searches PolyHaven assets. | `asset_type`, `categories` |
| `download_polyhaven_asset` | Downloads a PolyHaven asset. | `asset_id`, `asset_type`, `resolution`, `file_format` |
| `set_texture` | Applies a downloaded texture. | `object_name`, `texture_id` |
| `set_ollama_model` | Sets the Ollama model. | `model_name` (str) |
| `set_ollama_url` | Sets the Ollama server URL. | `url` (str) |
| `get_ollama_models` | Lists available Ollama models. | None |
## Troubleshooting
If you encounter issues:
- Ensure Ollama and the `blender-open-mcp` server are running.
- Check Blender’s add-on settings.
- Verify command-line arguments.
- Refer to logs for error details.
For further assistance, visit the [GitHub Issues](https://github.com/dhakalnirajan/blender-open-mcp/issues) page.
---
Happy Blending with AI! 🚀