Skip to main content
Glama

Blender AI MCP Server & Live Bridge

License: MIT Python 3.10+ MCP Protocol

An AI Model Context Protocol (MCP) server and bidirectional live bridge for Blender 3D. Connect AI assistants (such as Google Antigravity, Claude Desktop, Cursor, or OpenCode) directly to an active Blender session for real-time 3D scene inspection, geometry creation, Python script execution, and rendering.


Architecture Overview

+-------------------------------------------------------------+
| AI Agent / Client (Claude, Antigravity, Cursor)             |
+-------------------------------------------------------------+
                               |
                        MCP Protocol (JSON-RPC stdio)
                               v
+-------------------------------------------------------------+
| Blender FastMCP Server (mcp_server.py)                      |
| Exposes standard MCP tools                                  |
+-------------------------------------------------------------+
                               |
                        HTTP REST API (Port 9876)
                               v
+-------------------------------------------------------------+
| Blender Live Bridge (blender_bridge.py / blender_addon.py)  |
| Main-Thread Execution Queue (bpy.app.timers)                |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| Blender 3D Engine (bpy / bmesh / cycles / eevee)            |
+-------------------------------------------------------------+

Related MCP server: Blender MCP Bridge

Features

  • Thread-Safe Live Bridge: Executes all bpy and bmesh commands exclusively on Blender's main thread via bpy.app.timers to eliminate UI locks and crashes.

  • Full Scene Inspection: Retrieve detailed object hierarchies, types, locations, bounding boxes, mesh polygon counts, and active camera settings.

  • Arbitrary Python Automation: Execute complex Blender Python scripts dynamically, with captured stdout, stderr, and returned dictionary results.

  • Parametric 3D Modeling: Create primitive meshes (cubes, cylinders, UV spheres, icospheres, cones, planes), apply translations, rotations, scaling, and configure modifiers.

  • Lighting & Camera Setup: Create and position cameras aimed at 3D targets, configure focal lengths, and set up scene illumination.

  • PBR Material Creation: Generate and configure Principled BSDF materials with base color, metallic, roughness, and transmission.

  • Viewport Rendering: Capture high-resolution viewport or Cycles/Eevee render frames and return image file paths directly to the AI model.

  • Two Integration Modes: Run as a simple script inside Blender's Text Editor or install as a permanent Blender Add-on with a dedicated Sidebar (N-panel) UI.


Installation & Quickstart

1. Install Package

git clone https://github.com/Ziad-Amr1/blender-ai-mcp.git
cd blender-ai-mcp
pip install -e .

2. Start the Live Bridge inside Blender

Option A: Quick Script (No installation needed)

  1. Open Blender.

  2. Go to the Scripting workspace.

  3. Open blender_bridge.py and click Run Script (Alt+P).

  4. The bridge starts listening on http://127.0.0.1:9876.

Option B: Install as Blender Add-on

  1. In Blender, navigate to Edit > Preferences > Add-ons > Install...

  2. Select blender_addon.py.

  3. Enable the checkbox for 3D View: Blender AI Bridge.

  4. In the 3D Viewport, press N to open the sidebar, select the AI Bridge tab, and click Start Bridge Server.


MCP Client Configuration

Add the server to your MCP client configuration file:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "blender": {
      "command": "blender-mcp",
      "env": {
        "BLENDER_BRIDGE_URL": "http://127.0.0.1:9876"
      }
    }
  }
}

Antigravity (agy / settings.json)

{
  "mcp": {
    "servers": {
      "blender": {
        "command": "blender-mcp"
      }
    }
  }
}

Exposed MCP Tools

Tool Name

Description

blender_get_connection_status

Check if Blender Live Bridge is active and view scene stats.

blender_inspect_scene

Retrieve list of all scene objects, bounding boxes, and active camera.

blender_execute_python

Run arbitrary bpy/bmesh Python code with captured outputs.

blender_query_objects

Query objects matching specific names or types (MESH, CAMERA, etc.).

blender_select_objects

Select, deselect, or set active object by name.

blender_create_primitive

Spawn parametric primitive geometry at specified coordinates.

blender_transform_object

Move, rotate, or scale objects in world or relative coordinates.

blender_apply_modifier

Add and apply modifiers (Subsurf, Bevel, Boolean, Mirror, Solidify).

blender_setup_camera_light

Position cameras aimed at targets and configure lighting.

blender_create_material

Create PBR Principled BSDF materials with custom surface parameters.

blender_delete_objects

Safely remove scene objects and purge orphan mesh datablocks.

blender_render_viewport

Trigger viewport render or full F12 render and save image.

blender_import_model

Import standard 3D formats (.stl, .obj, .fbx, .gltf, .ply).

blender_export_model

Export scene or selected objects to STL, OBJ, FBX, or GLTF.


License

Open source under the MIT License.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to drive a live Blender session over MCP by creating and transforming primitives, building and assigning materials, inspecting scenes and objects, capturing viewport screenshots, and executing arbitrary bpy Python. Commands are relayed over a local TCP bridge to a Blender add-on and executed on Blender's main thread, supporting multiple simultaneous AI clients.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to control a live Blender session, manage scenes, objects, materials, and renders, download PolyHaven assets, and switch between multiple LLM backends at runtime.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to interact with a local Blender desktop application through a TCP bridge for scene inspection, rendering, asset export, visual comparison, and controlled mesh operations.
      MIT