# Blender MCP NextGen 🍊⚡

> **Next-Generation Model Context Protocol (MCP) Server & Addon Suite — Antigravity & Claude Friendly!**

Blender MCP NextGen connects AI assistants (such as **Antigravity AI Agent**, **Claude Desktop**, **Cursor**, **VS Code**, or custom LLMs) to Blender 3D using the official **Model Context Protocol (MCP)**. It enables natural language 3D modeling, automated scene inspection, PBR material creation, viewport visual feedback, asset importing, and background rendering.

---

## ✨ Features & Enhancements

- 🤖 **Antigravity & Claude Friendly**: Native MCP stdio integration with ready-to-use config templates ([mcp_antigravity.json](file:///c:/Users/swatm/Downloads/Blender/mcp_antigravity.json) & [antigravity_instructions.md](file:///c:/Users/swatm/Downloads/Blender/antigravity_instructions.md)).
- 🛡️ **AST Security Guardrails**: Built-in Python AST analyzer inspects generated code before execution to prevent harmful system commands or unwanted operations.
- 🎨 **Redesigned Blender Addon UI**: A sleek, dark-themed N-Panel ("MCP Assistant") inside Blender featuring live server status badges, active TCP socket port settings, quick lighting tools, and a real-time execution console.
- 📸 **Viewport Visual Feedback**: Multi-modal AI support with `capture_viewport` to take snapshot images of the active 3D viewport.
- 🌿 **PolyHaven Asset Library Search**: Instantly query and import free HDRIs, 3D models, and PBR textures into your Blender scene.
- 💡 **PBR Material Manager**: Quick helper commands to apply custom metallic, roughness, and hex color properties to 3D meshes.
- 🌐 **Web Setup Dashboard**: Interactive local dashboard for generating MCP client JSON configurations and viewing server diagnostics.

---

## 🚀 Quick Start Guide

### 1. Requirements
- **Blender**: 3.0 or higher (compatible with Blender 4.x)
- **Python**: 3.10 or higher

### 2. Install Server Dependencies
```bash
pip install -r requirements.txt
```

### 3. Install Addon in Blender
1. Open **Blender**.
2. Go to **Edit > Preferences > Add-ons**.
3. Click **Install...** at the top right and select `addon/blender_mcp_addon.py`.
4. Check the box to enable **Blender MCP NextGen**.
5. In the 3D Viewport, press **N** to expand the sidebar and click the **MCP Assistant** tab.
6. Click **Start Listener** (Status should change to **ONLINE** 🟢).

---

## ⚙️ MCP Client Configurations

### For Antigravity AI Agent (`mcp_antigravity.json`)
```json
{
  "mcpServers": {
    "blender-nextgen": {
      "command": "python",
      "args": ["c:/Users/swatm/Downloads/Blender/server/blender_mcp_server.py"]
    }
  }
}
```

### For Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "blender-nextgen": {
      "command": "python",
      "args": ["c:/Users/swatm/Downloads/Blender/server/blender_mcp_server.py"]
    }
  }
}
```

### For Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "blender-nextgen": {
      "command": "python",
      "args": ["c:/Users/swatm/Downloads/Blender/server/blender_mcp_server.py"]
    }
  }
}
```

---

## 🛠️ MCP Tools Reference

| Tool Name | Description |
|---|---|
| `execute_blender_code` | Executes safe Python code inside Blender with stdout, stderr, and error tracebacks. |
| `get_scene_info` | Returns structured JSON topology of objects, lights, cameras, active materials, and render settings. |
| `capture_viewport` | Takes a screenshot snapshot of the current 3D viewport for visual AI context. |
| `fetch_polyhaven_asset` | Downloads and imports HDRIs, textures, or models from PolyHaven. |
| `manage_material` | Creates or updates PBR materials with hex colors, metallic, and roughness values. |
| `render_scene` | Triggers Eevee or Cycles rendering and saves the output. |

---

## 🔒 Security Notice
All code sent via `execute_blender_code` is parsed and checked against `server/security_guardrails.py`. Forbidden modules (`os`, `sys`, `subprocess`, `shutil`) and execution statements (`eval`, `exec` on system level) are blocked by default.