# 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