README.md•4.2 kB
# Blender MCP Server 🎨🤖
A highly optimized **Model Context Protocol (MCP)** server that connects AI Assistants (like Claude, Gemini, etc.) directly to **Blender**.
This allows you to control Blender using natural language to create objects, apply textures, manage scenes, and more, with a focus on **token efficiency** and **speed**.
## ✨ Features
* **🚀 Optimized for AI**: Uses compact JSON and output truncation to save 75%+ tokens compared to raw scripting.
* **🔌 Direct Integration**: Works with any MCP-compliant client (Cursor, Windsurf, etc.).
* **🛠️ Powerful Tools**:
* `create_primitive`: Create Cubes, Spheres, Cones, etc.
* `transform_object`: Move, Rotate, Scale.
* `apply_texture`: Auto-Join objects, Smart UV Project, and apply textures in one go.
* `apply_material_preset`: Apply Gold, Glass, Plastic, etc. instantly.
* `scatter_objects`: Randomly distribute objects.
* `get_scene_info`: See what's in your scene (with filtering).
* **UI Control**: Dedicated panel in Blender to Start/Stop the server.
---
## 📦 Installation Guide
### 1. Prerequisites
* **Blender 3.0+** installed.
* **Python 3.10+** installed on your system.
* **Git** (optional, for cloning).
### 2. Setup the Project
Clone this repository or download the files:
```bash
git clone https://github.com/yourusername/blender-mcp.git
cd blender-mcp
```
### 3. Install Python Dependencies
**Option A: Local Python (Simple)**
Install the `mcp` library required for the server:
```bash
pip install mcp
```
**Option B: Using Docker (Clean & Isolated) 🐳**
If you prefer not to install Python dependencies locally, you can use Docker.
1. **Build the Image**:
```bash
docker build -t blender-mcp .
```
2. **Update MCP Config**:
Use the `docker` command instead of `python` in your IDE config (see Configuration section below).
### 4. Install the Blender Addon
1. Open **Blender**.
2. Go to **Edit > Preferences > Add-ons**.
3. Click **Install...** at the top right.
4. Navigate to this folder and select **`addon.py`**.
5. Click **Install Add-on**.
6. ✅ Check the box next to **Interface: MCP Connector** to enable it.
---
## ⚙️ Configuration (AI IDE)
You need to tell your AI IDE (like Cursor or Windsurf) about this MCP server.
### Option A: Local Python Config
```json
{
"mcpServers": {
"blender-mcp": {
"command": "python",
"args": [
"ABSOLUTE/PATH/TO/blender-mcp/server.py"
],
"env": {
"BLENDER_HOST": "127.0.0.1",
"BLENDER_PORT": "9876"
}
}
}
}
```
### Option B: Docker Config
If you built the Docker image, use this configuration:
```json
{
"mcpServers": {
"blender-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env", "BLENDER_HOST=host.docker.internal",
"blender-mcp"
]
}
}
}
```
*Note: `host.docker.internal` allows the Docker container to talk to Blender running on your host machine.*
*Replace `ABSOLUTE/PATH/TO/...` with the actual full path to where you saved this folder.*
---
## 🚀 Usage
### 1. Start the Server in Blender
1. Open the 3D Viewport in Blender.
2. Press **N** to open the Sidebar.
3. Click the **MCP** tab.
4. Click **Start Server** ▶️.
* *Status should change to "Connected".*
### 2. Connect & Prompt!
Restart your AI IDE to load the new MCP config. Now you can ask things like:
> "Create a low poly tree with a brown cylinder trunk and a green cone top."
> "Scatter 50 gold cubes in a radius of 10 meters."
> "Clear the scene and make a red monkey head."
> "Apply this texture 'C:/Textures/Wood.jpg' to the Cube."
---
## 🛠️ Troubleshooting
* **Connection Refused?**
* Make sure you clicked **Start Server** in the Blender MCP panel.
* Check if the port `9876` is blocked by a firewall.
* **"Object not found" error?**
* Ensure the object name matches exactly (case-sensitive). Use `get_scene_info` to check names.
* **Textures not showing?**
* Make sure you are in **Material Preview** or **Rendered** mode in Blender (Press `Z`).
---
## 📜 License
MIT License