Blender-Mind-MCP (Produktions-AI-3D-Modellierung & Blender-Bridge)

Ein produktionsreifer Model Context Protocol (MCP)-Server und Blender-Addon-Ökosystem für automatisiertes 3D-Modelling, prozedurale Asset-Generierung, Shader-Erstellung und multimodale Viewport-Inspektion.

🏗️ Vorarbeiten & Architektonische Inspiration

Dieses Projekt übernimmt architektonische Lehren und Benchmarks von führenden GitHub-Blender-AI-Projekten (wie ahujasid/blender-mcp und djeada/blender-mcp-server):

1. Thread-sicheres Main-Thread-Dispatching: Blenders Python-C-API (bpy) ist nicht threadsicher. Wie in Community-Issue-Audits festgestellt wurde, führt die Ausführung von bpy-Aufrufen in rohen Socket-Listener-Threads zu Speicherkorruptionen und Segmentierungsfehlern. Unser Blender-Addon verwendet eine threadsichere queue.Queue in Verbindung mit bpy.app.timers, um sicherzustellen, dass alle Szenenmodifikationen ausschließlich in Blenders Haupt-Render-/GUI-Loop ausgeführt werden.

2. Undo-Schritt-Isolation: Jede AI-Codeausführung wird mit bpy.ops.ed.undo_push() eingeklammert, was nahtlose Ctrl+Z-Rollbacks in Blender ermöglicht.

3. Multimodale Viewport-Erfassung: Verwendet Offscreen-OpenGL-Rendering (bpy.ops.render.opengl), um Base64-kodierte PNG-Screenshots des 3D-Viewports direkt an multimodale Vision-Modelle zurückzugeben.

4. Hexagonale Architektur (Ports & Adapters): Entkoppelt die reine 3D-Geometrieerzeugung von physischen Treibern und unterstützt sowohl Live-Socket-Verbindungen (127.0.0.1:9876), Headless-CLI-Batching (blender -b) als auch Offline-prozedurale glTF-Binärsimulation.

Related MCP server: Blender MCP Server

📦 Projektstruktur

blender-mind-mcp/
├── addon/
│   └── blender_mcp_addon.py       # Full Blender 3.x/4.x Addon (UI Sidebar Panel, Socket Server, Viewport Capture)
├── src/
│   ├── index.ts                   # stdio JSON-RPC MCP Server entry point
│   ├── bridge/
│   │   └── socket_client.ts       # Robust TCP Socket Client with reconnect & timeout handling
│   ├── core/
│   │   └── domain/
│   │       ├── types.ts           # 3D Domain Types (Scene, Mesh, Material, Modifier, Transform)
│   │       ├── scene.ts           # Pure in-memory 3D scene graph & polygon math
│   │       └── bpy_generator.ts   # Modern Blender 4.x/3.x Python code synthesizer
│   ├── ports/
│   │   └── driver.port.ts         # BlenderDriverPort interface specification
│   ├── adapters/
│   │   ├── live_socket.adapter.ts # Live Socket Adapter (talks to active Blender GUI)
│   │   ├── blender_cli.adapter.ts # Headless CLI Adapter (talks to blender.exe)
│   │   └── mock_geometry.adapter.ts # Offline Simulation Adapter (glTF & OBJ binary synthesis)
│   └── tools/
│       └── index.ts               # 10 MCP Tools registry & dispatcher
├── tests/
│   ├── unit/                      # L1: Domain math & Python code generation
│   ├── contract/                  # L2: MCP tool schemas & argument contracts
│   ├── integration/               # L3: Binary glTF headers & TCP Socket Bridge
│   └── run_tests.ts               # Complete Truth Ladder test runner
├── package.json
└── tsconfig.json

🚀 Schnellstart

1. Addon in Blender installieren

1. Öffnen Sie Blender (3.6+ oder 4.x).

2. Gehen Sie zu Edit > Preferences > Add-ons > Install... (oder dem Install-from-Disk-Pfeil in 4.2+).

3. Wählen Sie addon/blender_mcp_addon.py.

4. Aktivieren Sie Development: Blender MCP Bridge.

5. Drücken Sie im 3D-Viewport N, um die Seitenleiste zu öffnen, klicken Sie auf den Tab Blender MCP und klicken Sie auf Start MCP Server.

2. MCP-Client konfigurieren (Antigravity / Claude / Codex)

Fügen Sie zu Ihrer Projekt- oder globalen MCP-Konfiguration hinzu (.mcp.json):

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": [
        "--disable-warning=ExperimentalWarning",
        "--experimental-strip-types",
        "C:/Users/a1691/Documents/antigravity/noble-hypatia/src/index.ts"
      ]
    }
  }
}

🛠️ 10 Kern-MCP-Tools

🧪 Truth-Ladder-Verifikation

npm test

Führt alle 6 Test-Suiten über die 4-stufige Truth Ladder aus:

• L1 Unit: 100 % reines Domain-Modeling & Python-Code-Synthesizer-AST-Prüfungen.

• L2 Contract: Schema-Definitionen und Dispatch-Verifikation für alle 10 Tools.

• L3 Integration: Binärer glTF-v2-Header (0x46546C67) & OBJ-Strukturvalidierung.

• L3 Integration: Live-TCP-Socket-Client-Server-Loopback-Test auf 127.0.0.1:9899.

• L4 E2E: Live-stdio-JSON-RPC-Pipe-Roundtrip.