# 🚀 Blender MCP Link

[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-purple.svg)](https://modelcontextprotocol.io)
[![Blender](https://img.shields.io/badge/Blender-5.1%20%7C%205.0%20%7C%204.x-orange.svg?logo=blender)](https://blender.org)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

An extremely robust, production-grade **Model Context Protocol (MCP)** server that establishes a **live, interactive two-way connection** with your active **Blender** session. Control 3D scenes, construct geometry, modify shaders, and render viewports—all directly using natural language prompts via your favorite AI assistants (such as Antigravity, Claude Desktop, Cursor, or VS Code).

---

## 🌟 Key Features

* 🐍 **Main-Thread Safe Execution:** Runs a background socket server in a thread and safely passes actions to Blender’s main thread via a queue and timer loop, avoiding critical API-related crashes.
* 📦 **Complete Scene Inventory:** Exposes structured details of all collections, geometry, cameras, point lights, dimensions, parent hierarchies, and applied materials.
* 🛠️ **High-Level Mesh Generator:** Create mesh primitives (Cubes, Spheres, Cylinders, Cones, Planes, Toruses) directly with customizable scale, names, and coordinates.
* 🎨 **Shader & Material Control:** Apply beautiful Principal BSDF materials dynamically with custom Hex color codes, roughness, metallic, and shader node linking.
* 📸 **Real-time Viewport Render:** Instantly trigger background renders using Blender’s EEVEE engine to see updates directly in your chat screen.

---

## 🏗️ Architecture Design

Unlike naive implementations that attempt to invoke the Blender API (`bpy`) from secondary socket threads (which causes immediate memory access violation crashes), **Blender MCP Link** employs a thread-safe **Message-Queue architecture**:

```mermaid
graph TD
    subgraph AI Client
        LLM[AI Client / Claude / Cursor]
    end

    subgraph MCP Server [Local CLI Process]
        FastMCP[FastMCP Server]
        SocketClient[TCP Socket Client]
    end

    subgraph Blender Session [Active Blender 5.1 GUI]
        SocketServer[Background TCP Server Thread]
        Queue[Thread-Safe Task Queue]
        Timer[Blender App Timer Loop - Main Thread]
        bpy[Blender Python API]
    end

    LLM <-->|Model Context Protocol| FastMCP
    FastMCP <-->|Function Calls| SocketClient
    SocketClient <-->|TCP Port 5555| SocketServer
    SocketServer -->|1. Enqueue Script| Queue
    Timer -->|2. Dequeue Script| Queue
    Timer -->|3. Run Script| bpy
    bpy -->|4. Return Output/Log| Timer
    Timer -->|5. Send Response| SocketServer
    SocketServer -->|6. Return JSON| SocketClient
```

---

## ⚡ Quick Start Setup

### Step 1: Install the Blender Addon

1. Open your **Blender** application.
2. Download or copy the [`addon.py`](./addon.py) file to a location on your computer.
3. In Blender, open **Edit > Preferences > Add-ons**.
4. Click **Install...** in the top-right corner of the Add-on menu.
5. Select [`addon.py`](./addon.py) and click **Install Add-on**.
6. Check the box next to **Development: Blender MCP Link Server** to enable it.
7. Open the 3D Viewport sidebar (press `N` on your keyboard) and navigate to the **MCP Link** tab.
8. Click **Start Server**. You will see the status change to **"Running"** (listening on `127.0.0.1:5555`).

---

### Step 2: Configure the MCP Server in your LLM Client

Ensure you have the ultra-fast Python package manager **`uv`** installed. If not, get it from [astral.sh/uv](https://astral.sh/uv).

#### For Claude Desktop
Add this to your `claude_desktop_config.json` (typically located in `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "blender-mcp-link": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "D:\\03_Projects\\AI_Projects\\Competitions\\Robotex\\blender-mcp-link",
        "server.py"
      ]
    }
  }
}
```

#### For Cursor / VS Code (Cline / Roo Code)
Add a new MCP server with the following settings:
* **Name:** `BlenderMCP`
* **Type:** `command`
* **Command:** `uv run --directory "D:\03_Projects\AI_Projects\Competitions\Robotex\blender-mcp-link" server.py`

---

## 🛠️ Expose Tools Reference

Once connected, the AI will have access to the following tools:

### 1. `get_scene_inventory`
* **Purpose:** Queries the Blender scene and returns structured information about all assets.
* **Returns:** JSON string including collections, cameras, lights, meshes, face counts, scales, and parents.

### 2. `execute_script(code: str)`
* **Purpose:** Runs arbitrary Blender Python code in the main execution thread.
* **Returns:** Captures `stdout` (prints) and `stderr` (exceptions and tracebacks) and returns them as a clean string.

### 3. `create_mesh_primitive(type: str, name: str, location: list, scale: list)`
* **Purpose:** Generates high-quality shapes without writing raw Python code.
* **Valid Types:** `CUBE`, `SPHERE`, `CYLINDER`, `CONE`, `TORUS`, `PLANE`.

### 4. `apply_principled_material(object_name: str, color_hex: str, roughness: float, metallic: float)`
* **Purpose:** Quick creation and binding of standard nodes-based BSDF materials to meshes.

### 5. `render_viewport(output_path: str)`
* **Purpose:** Renders the scene from the active camera view and outputs a high-resolution PNG image.

---

## 🛡️ License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🤝 Contributing

We welcome issues, feature requests, and pull requests! For major changes, please open an issue first to discuss what you would like to change.