🚀 Blender MCP Link

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:

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 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 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.

For Claude Desktop

Add this to your claude_desktop_config.json (typically located in %APPDATA%\Claude\claude_desktop_config.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 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.