blender-mcp

Ein MCP-Server, der Blender-.blend-Dateien erstellt. Er greift auf zwei Arten auf Blender zu:

• Headless – jeder Aufruf startet einen neuen blender --background-Prozess. Deterministisch, immer verfügbar und die richtige Wahl zum Generieren von Dateien.

• Live – ein kleines Blender-Addon öffnet einen lokalen Port, sodass der Server das bereits geöffnete Blender-Fenster steuern kann und Sie zusehen können.

Beide Wege führen denselben Handler-Code aus, sodass ein Skript in beiden Fällen identisch funktioniert. Eine lokale Web-Oberfläche ermöglicht das Hochladen von Referenzbildern und das Ausführen von Generierungsaufträgen mit denselben Werkzeugen.

Anforderungen

Related MCP server: Blender MCP

Einrichtung

uv sync                                        # create .venv and install
cp .env.example .env                           # then set BLENDER_MCP_EXECUTABLE
uv run python scripts/build_addon.py --install # build + install the Blender addon

Wenn Sie .env auslassen, durchsucht der Server Ihren PATH und die standardmäßigen Program Files/Blender Foundation/Blender <version>-Ordner auf jedem Laufwerk und bevorzugt die neueste gefundene Version.

Aktivieren der Live-Bridge

Das Addon ist installiert, aber inaktiv, bis Sie es starten:

1. Öffnen Sie Blender.

2. Drücken Sie N im 3D-Viewport, um die Seitenleiste anzuzeigen.

3. Öffnen Sie den MCP-Tab und klicken Sie auf Start MCP Bridge.

Aktivieren Sie Start listening on launch in den Addon-Einstellungen, um diesen Schritt jedes Mal zu überspringen.

Verbinden eines MCP-Clients

.cursor/mcp.json registriert den Server bereits für dieses Projekt. Um ihn überall verfügbar zu machen, kopieren Sie diesen Block in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\Users\\josef\\Projects\\blender-mcp", "blender-mcp"]
    }
  }
}

Qualitäts-Workflow

Die Generierungsqualität kommt vom Hinsehen, nicht von einem einzigen Skript-Dump:

1. list_references / view_reference – zuerst Referenzbilder öffnen

2. create_blend aus studio oder product

3. In kleinen run_script-Schritten aufbauen; apply_material für Metall/Plastik/Gummi/Glas/Holz

4. preview_views – mehrwinklige EEVEE-Vorschauen; mit view_image mit Referenzen vergleichen

5. Korrigieren, erneut vorschauen

6. Finales render / render_and_view (CYCLES nur für Finale; EEVEE während Iterationen)

Lokale Web-Oberfläche

uv run blender-mcp-web
# open http://127.0.0.1:8765

Laden Sie Referenzbilder hoch, geben Sie einen Prompt ein und durchsuchen Sie Aufträge unter output/jobs/.

• Mit BLENDER_MCP_LLM_API_KEY in .env – die Seite führt einen begrenzten multimodalen Agenten aus, der dieselben Blender-Werkzeuge aufruft (OpenAI-kompatibel oder Anthropic über BLENDER_MCP_LLM_PROVIDER).

• Ohne einen Schlüssel – Uploads und Auftragsseiten funktionieren trotzdem; öffnen Sie den Auftrag in Cursor und bitten Sie den MCP-Agenten, aus output/jobs/<id>/refs zu bauen.

Werkzeuge

Skripte schreiben

run_script und das script-Argument von create_blend werden in einem Namensraum ausgeführt, in dem bpy, mathutils, math, D (bpy.data) und C (bpy.context) bereits gebunden sind. Senden Sie Daten zurück, indem Sie result zuweisen oder emit(value) aufrufen.

Vorlagen

Layout

addon/blender_mcp_addon/   Blender extension + shared handlers (incl. preview_views)
src/blender_mcp/
  server.py                MCP tools
  refs.py                  reference image library
  materials.py             procedural material presets
  templates.py             starter scenes
  agent/                   bounded multimodal generation loop
  web/                     FastAPI UI (templates + static)
  headless.py / bridge.py  Blender process / live socket
scripts/                   build, install, verification
output/                    .blend files, renders, refs/, jobs/

Testen

uv run pytest -m "not blender"   # fast
uv run pytest                    # includes real Blender runs
uv run python scripts/check_server.py
uv run python scripts/verify_live_bridge.py

Hinweise und Einschränkungen

• run_script führt beliebiges Python innerhalb von Blender aus. Halten Sie die Bridge auf Loopback.

• Lange Render-Vorgänge blockieren die Live-Oberfläche, bis sie abgeschlossen sind.

• viewport_screenshot ist nur live verfügbar.

• Cycles verwendet die CPU, es sei denn, Sie aktivieren ein GPU-Gerät in den Blender-Einstellungen.

• Der Web-Agent benötigt ein multimodales Modell, das Tool-Aufrufe und Bilder unterstützt.