Blender 2D MCP

KI-gesteuertes 2D-Zeichnen und -Animieren für Blender 5.x über das Model Context Protocol. Ermöglicht MCP-Clients (Claude Desktop, Cursor, VS Code Copilot Agent-Modus, …), Grease-Pencil-Zeichnungen, Keyframes, Materialien und Renderings direkt in einer laufenden Blender-Instanz zu erstellen.

Basiert auf Blenders GPv3-API (bpy.ops.grease_pencil.*, GreasePencilDrawing), modelliert nach ahujasid/blender-mcp.

flowchart LR
    A[MCP Client<br/>Claude / Cursor / VS Code] <-->|stdio / JSON-RPC| B[blender-2d-mcp<br/>FastMCP server]
    B <-->|TCP JSON<br/>localhost:9876| C[addon.py<br/>socket server in Blender]
    C -->|main thread| D[Grease Pencil API<br/>GPv3]

• addon.py — Blender-Add-on, das einen TCP-JSON-Befehlsserver einbettet. Befehle werden in eine Warteschlange gestellt und über bpy.app.timers im Hauptthread von Blender ausgeführt.

• src/blender_2d_mcp/server.py — FastMCP-stdio-Server, der die Befehle des Add-ons als MCP-Tools bereitstellt.

Voraussetzungen

• Nur Blender 5.2 LTS (das Add-on weigert sich, auf älteren Builds aktiviert zu werden; die verwendete GPv3-API-Oberfläche ist 5.2-spezifisch)

• Python ≥ 3.10 mit mcp[cli] (wird automatisch installiert)

Related MCP server: Blender MCP Bridge

Installation

1. Add-on in Blender installieren

1. In Blender: Bearbeiten > Einstellungen > Add-ons > Installieren…

2. Wähle addon.py aus diesem Repository aus.

3. Aktiviere Interface: Blender 2D MCP.

4. Öffne die Seitenleiste (Ansicht > Seitenleiste, oder drücke N) → Tab Blender2DMCP.

5. Klicke auf Mit MCP-Client verbinden (Standardport 9876). Lasse Blender laufen.

Tipp: blender-2d-mcp --install-addon kopiert addon.py in deinen Downloads-Ordner und gibt diese Schritte aus.

2. Einen MCP-Client verbinden

Der Server bindet nur an localhost — für die lokale Nutzung ist kein Authentifizierungstoken erforderlich.

Option A — uvx (ohne Installation):

uvx --from "g:\My Projects\blender-2d-mcp" blender-2d-mcp

Option B — Editierbare Installation:

cd "g:\My Projects\blender-2d-mcp"
pip install -e .
blender-2d-mcp            # runs the stdio MCP server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"]
    }
  }
}

Cursor (.cursor/mcp.json) oder generische stdio-Clients:

{
  "mcpServers": {
    "blender-2d-mcp": {
      "command": "C:\\Path\\To\\Python\\Scripts\\blender-2d-mcp.exe",
      "args": []
    }
  }
}

VS Code / GitHub Copilot Chat (.vscode/mcp.json — bereits in diesem Repository enthalten):

{
  "servers": {
    "blender-2d-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"],
      "env": {}
    }
  }
}

Alternativ, wenn blender_2d_mcp in einer Umgebung per pip installiert ist, verwende das Python dieser Umgebung: "command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"].

Zur Verwendung: Öffne Copilot Chat, stelle das Modus-Dropdown auf Agent, und die Blender-Tools werden verfügbar (#blender-2d-mcp). Starte/stoppe/starte den Server über die Befehlspalette mit MCP: Server auflisten. Lade das VS-Code-Fenster nach dem Bearbeiten von mcp.json neu.

Die 2D-Leinwand

Mit setup_2d_scene wird der Viewport auf eine orthografische Frontansicht gesetzt, sodass die Zeichenebene die Welt-XZ-Ebene ist:

Einheiten sind Meter (Blender-Standard); ein 1920×1080-HD-Frame bei Standard-Kamerazoom erstreckt sich horizontal über ungefähr ±5 Einheiten.

Tool-Katalog

Typischer Arbeitsablauf

1. get_gp_scene_info + get_viewport_screenshot — sehen, was vorhanden ist.

2. setup_2d_scene → create_gp_object, wenn man neu beginnt.

3. Zeichne mit gp_draw_shape / gp_draw_stroke; übergebe frame_number, um Striche auf Schlüsselposen zu platzieren (Frames werden automatisch erstellt). Verwende gp_draw_strokes, um detaillierte Zeichnungen in einem Stapel zu zeichnen.

4. Gefüllte Formen: Erstelle ein Material mit fill_alpha > 0, dann fill=True + fill_material.

5. Animiere 'on twos' (Schlüsselposen alle 2 Frames bei 24 fps): Kopiere Posen mit gp_copy_frame, bearbeite sie mit gp_transform_stroke, dann gp_interpolate für Zwischenbilder. Füge einen NOISE-Modifikator für handgezeichneten Wackel hinzu.

6. Rendere mit render_animation(use_video=True) und frage get_render_status ab.

7. Mache nach Änderungen immer einen Screenshot, um visuell zu überprüfen. Fehler können über undo rückgängig gemacht werden.

Entwicklung

pip install -e ".[dev]"
python -m pytest tests/ -v

Die Testsuite führt den TCP-Transport des Add-ons außerhalb von Blender aus, indem sie die Serverklasse per AST-Lifting gegen ein Fake-bpy testet – keine Blender-Installation erforderlich. Handler-Logik, die echte Grease-Pencil-Daten berührt, muss innerhalb von Blender verifiziert werden.

Fehlerbehebung

Lizenz

MIT