https://github.com/dhakalnirajan/blender-open-mcp
https://github.com/dhakalnirajan/blender-open-mcp
Last synced: 4 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 (8 months ago)
- Default Branch: main
- Last Pushed: 2025-03-14T10:45:44.000Z (8 months ago)
- Last Synced: 2025-03-14T11:29:28.350Z (8 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
- awesome-mcp-servers - Blender Open MCP - A server that integrates Blender with local AI models via the Model Context Protocol (MCP), allowing users to control Blender using natural language prompts for 3D modeling tasks. This is directly relevant as an example of an MCP server. ([Read more](/details/blender-open-mcp.md)) `blender` `3d-modeling` `ai-integration` `natural-language` (Media Processing MCP Servers)
- awesome-mcp-servers - **blender-open-mcp** - Open Models MCP for Blender Using Ollama `python` `blender` `blender-addon` `blender3d` `mcp` `pip install git+https://github.com/dhakalnirajan/blender-open-mcp` (🤖 AI/ML)
- awesome-mcp-servers - **blender-open-mcp** - Open Models MCP for Blender Using Ollama `python` `blender` `blender-addon` `blender3d` `mcp` `pip install git+https://github.com/dhakalnirajan/blender-open-mcp` (AI/ML)
- metorial-index - Blender Integration with AI Models - Integrates Blender with local AI models using natural language prompts to facilitate 3D modeling tasks. Employs the Model Context Protocol for structured communication and includes a Blender add-on for enhanced usability. (Developer Tools)
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 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! 🚀