blender-lab-mcp-client

Ein MCP-Client, der das eigentliche Drahtprotokoll des offiziellen „Blender Lab“-MCP-Add-ons von Blender.org spricht und dieselben 27 Werkzeuge wie djeada/blender-mcp-server bereitstellt — aber gegen blender.org/lab/mcp-server arbeitet statt gegen das im Projekt gebündelte eigene Add-on.

Warum dieses Projekt existiert

Es gibt (mindestens) zwei nicht verwandte „Blender + MCP“-Projekte, die zufällig denselben Namen, denselben Standardport und ein ähnliches Konzept teilen:

1. djeada/blender-mcp-server — liefert ein zusammengehöriges Paar: ein eigenes Blender-Add-on und einen Python-MCP-Client, die über localhost:9876 ein zeilenumbruchgetrenntes {"id", "command", "params"} / {"success", "result"}-Protokoll sprechen.

2. Das offizielle Blender-Lab-Add-on (blender.org/lab/mcp-server, Maintainer „Blender Authors“) — ein völlig separates Projekt. Es lauscht ebenfalls auf localhost:9876, liefert aber nur die Add-on-Seite. Es spricht nullbytegetrennte {"type": "execute", "code": ..., "strict_json": ...}-Anfragen und {"status": "ok"|"error", "result": ...}-Antworten, verfügt über keinen eingebauten Dispatcher für benannte Befehle (es führt lediglich rohes Python gegen bpy aus) und schließt seine TCP-Verbindung nach jeder einzelnen Anfrage.

Wenn Sie das offizielle Blender-Lab-Add-on installieren, aber einen MCP-Client konfigurieren, der auf djeada/blender-mcp-server ausgerichtet ist (z. B. über uvx blender-mcp-server), schlägt jeder Tool-Aufruf mit etwa Folgendem fehl:

Extra data: line 1 column 51 (char 50)

oder, beim nächsten Aufruf:

Lost connection to Blender: Blender connection closed

Das ist keine wackelige Verbindung, kein veralteter Prozess und kein Blender-Fehler — es sind zwei nicht verwandte Protokolle, die aneinander vorbeireden. Der djeada-Client sendet eine zeilenumbruchterminierte Anfrage, die das Add-on nie erkennt; das Add-on lässt den Client in einen Timeout laufen, sendet einen kleinen nullbyteterminierten Fehler zurück, und das readline() des Clients scheitert an dem überzähligen Nullbyte direkt nach dem JSON-Objekt.

Dieses Paket implementiert jedes der ursprünglichen 27 MCP-Werkzeuge neu, indem es das äquivalente bpy-Python erzeugt und es über das tatsächliche Protokoll des Blender-Lab-Add-ons sendet. Die Werkzeugnamen, Parameter und das Verhalten bleiben gleich — nur das darunterliegende Drahtformat ändert sich.

Installation

1. Installieren Sie das offizielle Blender-Lab-MCP-Add-on in Blender (Bearbeiten → Einstellungen → Add-ons → nach „MCP“ suchen oder über die Plattform für Erweiterungen) und stellen Sie sicher, dass es auf 127.0.0.1:9876 lauscht (Add-on-Einstellungen → Server starten).

2. Installieren Sie dieses Paket:

   git clone https://github.com/A-to-PC/blender-lab-mcp-client.git
   cd blender-lab-mcp-client
   pip install -e .

3. Richten Sie Ihren MCP-Client darauf aus. Für eine Konfiguration im Stil von mcp.json:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "blender-lab-mcp-client"
       }
     }
   }

   Oder führen Sie es direkt aus dem Quellcode aus, ohne Installation, über uv:

   {
     "servers": {
       "Blender": {
         "type": "stdio",
         "command": "uv",
         "args": ["run", "--project", "/absolute/path/to/blender-lab-mcp-client", "blender-lab-mcp-client"]
       }
     }
   }

Tool-Referenz

Die gleichen 27 Werkzeuge wie im Upstream — siehe Tool-Referenz von djeada/blender-mcp-server für die vollständige Tabelle (Szeneninspektion, Objektmanipulation, Materialien, Rendern/Export, Verlauf, Python-Ausführung, asynchrone Aufträge). Namen und Parameter sind unverändert; nur der darunterliegende Transport ist anders.

Bekannte Einschränkungen

• blender_python_exec_async / blender_job_status / blender_job_cancel / blender_job_list (nur Bridge-Transport) werden als synchron simuliert. Der eigentliche Mechanismus für verzögerte Aufträge des Add-ons erfordert, dass der ausgeführte Code selbst ein aufrufbares check_is_finished setzt, was nicht praktikabel generisch aus beliebigem übermitteltem Code erzeugt werden kann. Asynchrone Aufrufe gegen die Live-Blender-Sitzung laufen tatsächlich synchron ab und werden sofort als "succeeded" gemeldet. Für wirklich langlaufende Arbeiten (Physik-Bakes, schwere Simulationen) verwenden Sie stattdessen transport="headless" — dieser Pfad führt einen separaten blender -b-Hintergrundprozess aus und ist von dieser Einschränkung nicht betroffen.

• Eine Verbindung pro Anfrage. Das Add-on schließt seinen Socket nach jeder Antwort, daher kann dieser Client keine persistente Verbindung wiederverwenden — jeder Tool-Aufruf öffnet eine neue TCP-Verbindung. Das entspricht dem tatsächlichen Design des Add-ons; es ist keine Performance-Optimierung, die clientseitig „behoben“ werden könnte.

• Getestet gegen Blender 5.2 LTS mit dem Blender-Lab-Add-on. Der Hilfscode für Objekte/Materialien verwendet standardmäßige bpy.ops.*-Aufrufe und sollte mit jeder aktuellen Blender-Version funktionieren, wurde aber nicht über eine Versionsmatrix hinweg verifiziert.

Danksagung

Abgeleitet von djeada/blender-mcp-server (MIT-lizenziert) von Adam Djellouli — die MCP-Tooloberfläche (Namen, Parameter, Beschreibungen) und der headless.py-Transport für die Hintergrundausführung werden unverändert übernommen. Nur die BlenderConnection in server.py und die Übersetzungsschicht von Befehlen zu bpy-Code sind neu, um das Protokoll des offiziellen Blender-Lab-Add-ons anzusprechen anstelle des im Upstream gebündelten Add-ons.

Lizenz

MIT — siehe LICENSE.