blender-control-mcp

blender-control-mcp ist ein eigenständiger STDIO-MCP-Server, der Blender im Hintergrundmodus unter lokalem Windows sicher steuert. Er enthält keine LLM-, Naturspracheninterpretations- oder beliebigen Python-/Shell-Ausführungsfunktionen. Es können nur die 7 strukturierten Tools verwendet werden, die der Server bereitstellt, und die Eingaben werden sowohl auf dem Host als auch innerhalb von Blender validiert.

Systemvoraussetzungen

• Windows

• Python 3.12 oder höher

• Blender 5.2 LTS empfohlen

• Standard-Blender-Pfad: C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe

Related MCP server: blend-ai

Installation

Führen Sie im Projektstammverzeichnis mit PowerShell aus.

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Wenn sich Blender an einem anderen Ort befindet, legen Sie eine Umgebungsvariable fest.

$env:BLENDER_EXECUTABLE = "D:\Apps\Blender\blender.exe"

Optionale Umgebungsvariablen:

• BLENDER_EXECUTABLE: Pfad zu blender.exe

• BLENDER_TIMEOUT_SECONDS: Timeout für einen Vorgang, 1–3600 Sekunden, Standard 180 Sekunden

• BLENDER_CONTROL_WORKDIR: Stammverzeichnis für die Speicherung von Protokollen/Plänen von schreibgeschützten Prüfvorgängen. Standardwert ist %TEMP%\blender-control-mcp

Serverausführung

.\.venv\Scripts\blender-control-mcp.exe

Oder Sie können ihn wie folgt ausführen.

.\.venv\Scripts\python.exe -m blender_control_mcp.server

Da es sich um einen STDIO-Server handelt, werden bei normaler Ausführung keine interaktiven Eingabeaufforderungen oder regulären Protokolle auf stdout ausgegeben. Der MCP-Client startet den Prozess und tauscht JSON-RPC aus.

Codex-Verbindung

Codex unterstützt lokale STDIO-MCP-Server und kann in der Benutzerdatei ~/.codex/config.toml oder in der .codex/config.toml eines vertrauenswürdigen Projekts konfiguriert werden. Der folgende Pfad ist ein Beispiel, das die Standardposition dieses Repositorys verwendet.

[mcp_servers.blender_control]
command = "C:/Users/park/Desktop/dev_tool/blender-control-mcp/.venv/Scripts/python.exe"
args = ["-m", "blender_control_mcp.server"]
cwd = "C:/Users/park/Desktop/dev_tool/blender-control-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 300
default_tools_approval_mode = "writes"

[mcp_servers.blender_control.env]
BLENDER_EXECUTABLE = "C:/Users/park/Applications/blender-5.2.0-windows-x64/blender.exe"
BLENDER_TIMEOUT_SECONDS = "180"

Starten Sie Codex nach der Konfiguration neu und prüfen Sie den Verbindungsstatus mit /mcp oder codex mcp list. In der Benutzeroberfläche können Sie auch Settings → MCP servers → Add server → STDIO auswählen und dieselben command/args eingeben. Die neuesten Konfigurationselemente finden Sie in der OpenAI-Codex-MCP-Dokumentation.

Ein Beispiel für das Hinzufügen über die CLI ist wie folgt.

codex mcp add blender_control --env BLENDER_EXECUTABLE=C:\Users\park\Applications\blender-5.2.0-windows-x64\blender.exe -- C:\Users\park\Desktop\dev_tool\blender-control-mcp\.venv\Scripts\python.exe -m blender_control_mcp.server

Verbindung mit anderen MCP-Clients

Dies ist ein allgemeines Beispiel für Clients, deren STDIO-Serverkonfigurationsformat JSON ist. Den tatsächlichen Speicherort der Konfigurationsdatei und die Schlüsselnamen finden Sie in der Client-Dokumentation.

{
  "mcpServers": {
    "blender-control": {
      "command": "C:\\Users\\park\\Desktop\\dev_tool\\blender-control-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "blender_control_mcp.server"],
      "env": {
        "BLENDER_EXECUTABLE": "C:\\Users\\park\\Applications\\blender-5.2.0-windows-x64\\blender.exe"
      }
    }
  }
}

Tools

Alle Pfadeingaben sind Zeichenfolgen. Für Eingabe-Assets sind nur .glb, .blend und .fbx zulässig. target muss all oder ein Name sein, der einschließlich Groß-/Kleinschreibung exakt übereinstimmt. Wenn nichts gefunden wird oder die Angabe mehrdeutig ist, wählt der Server nicht willkürlich aus, sondern gibt den Fehler target_not_found/ambiguous_target zusammen mit einer Kandidatenliste zurück.

scene.inspect

Eingabe:

{"input_path":"C:\\assets\\chair.glb"}

data.objects gibt Name, Typ, Material-Slots, Anzahl der Mesh-Scheitelpunkte/Polygone, Abmessungen, Position und eine Modifier-Liste zurück.

{
  "success": true,
  "data": {
    "object_count": 1,
    "objects": [{
      "name": "Chair",
      "type": "MESH",
      "material_slots": ["Wood"],
      "vertex_count": 1200,
      "polygon_count": 800,
      "dimensions": [1.0, 1.1, 1.8],
      "location": [0.0, 0.0, 0.0],
      "modifiers": []
    }]
  }
}

material.list

Eingabe:

{"input_path":"C:\\assets\\chair.blend"}

Beispiel für die Rückgabe:

{
  "success": true,
  "data": {
    "material_count": 1,
    "materials": [{
      "name": "Wood",
      "base_color": [0.4, 0.2, 0.1, 1.0],
      "roughness": 0.55,
      "metallic": 0.0,
      "alpha": 1.0,
      "base_color_texture_linked": true
    }]
  }
}

asset.apply_material

base_color ist RGB oder RGBA im Bereich 0–1, und roughness, metallic und alpha liegen ebenfalls im Bereich 0–1. Mindestens ein geänderter Wert ist erforderlich.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Wood",
  "base_color":[0.1,0.3,0.8,0.75],
  "roughness":0.25,
  "alpha":0.75
}

Ziel ist ein exakter Materialname oder ein Objektname mit nur einem Material. Es werden modifizierte GLB-, BLEND- und FBX-Dateien erzeugt. Wenn ein Objekt mehrere Materialien hat, wird eine Materialkandidatenliste zurückgegeben und eine explizite Auswahl verlangt.

asset.transform

Jeder Vektor besteht aus 3 Zahlen. scale liegt pro Achse zwischen 0,001 und 1000, und mindestens ein geänderter Wert ist erforderlich.

{
  "input_path":"C:\\assets\\chair.glb",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "location":[0,0,1],
  "rotation_degrees":[0,0,90],
  "scale":[1.2,1.2,1.2]
}

Es werden modifizierte GLB-, BLEND- und FBX-Dateien erzeugt.

asset.add_modifier

Beispiel für Bevel-Eingabe:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"bevel",
  "width":0.03,
  "segments":3
}

Beispiel für Decimate-Eingabe:

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair",
  "modifier_type":"decimate",
  "ratio":0.5
}

Bevel akzeptiert nur width > 0–1000 und segments 1–16 (Standard 0,1/3). Decimate akzeptiert nur ratio 0,01–1 (Standard 0,5). Andere Modifier oder gemischte Parameter werden abgelehnt. Es werden alle drei modifizierten Formate erzeugt.

asset.set_smooth_shading

{
  "input_path":"C:\\assets\\chair.fbx",
  "output_directory":"C:\\assets\\outputs",
  "target":"Chair"
}

Setzt Smooth Shading auf die Ziel-Mesh-Polygone und erzeugt modifizierte GLB-, BLEND- und FBX-Dateien.

asset.export

{
  "input_path":"C:\\assets\\chair.blend",
  "output_directory":"C:\\assets\\exports",
  "formats":["glb","blend","fbx"]
}

formats muss mindestens eines aus glb, blend, fbx ohne Duplikate enthalten; es werden nur die angeforderten Formate erzeugt.

Gemeinsame Antworten und Artefakte

Jeder Aufruf gibt eine strukturierte Antwort zurück. Modifikations-/Export-Tools erstellen Artefakte unter <output_directory>/<operation_id>/, und Lese-Tools hinterlassen Protokolle unter dem temporären Arbeitsstammverzeichnis.

{
  "success": true,
  "operation_id": "9bc12a7f57f24f8ba9d9af2f78de3041",
  "operation": "asset.export",
  "artifacts": [
    "C:\\assets\\exports\\9bc12a7f57f24f8ba9d9af2f78de3041\\chair.glb"
  ],
  "summary": "asset.export completed successfully",
  "data": {"formats":["glb"],"artifact_count":1},
  "operation_path": "...\\operation.json",
  "log_path": "...\\blender.log",
  "log_excerpt": "Blender 5.2.0 ...",
  "command": ["...\\blender.exe","--background","..."],
  "exit_code": 0,
  "errors": []
}

Auch bei Fehlern werden nach Möglichkeit operation.json und blender.log hinterlassen, und es werden Fehlercode und Kandidaten wie folgt zurückgegeben.

{
  "success": false,
  "summary": "object target 'Seat' was not found",
  "artifacts": [],
  "errors": [{
    "code": "target_not_found",
    "message": "object target 'Seat' was not found",
    "candidates": ["Chair", "Table"]
  }]
}

Tests

Gesamttests:

.\.venv\Scripts\python.exe -m pytest -q

In Umgebungen ohne Blender wird automatisch nur der eine echte Blender-Integrationstest übersprungen, und die Unit-Tests bestehen.

# 빠른 단위 테스트만
.\.venv\Scripts\python.exe -m pytest -m "not integration" -q

# 실제 Blender 통합 테스트만
.\.venv\Scripts\python.exe -m pytest -m integration -q

Der Integrationstest erstellt eine kleine GLB-Datei und verifiziert dann in echtem Blender die Szenenprüfung, Materialfarben-/Rauhigkeits-/Transparenzänderungen, Skalierungsänderungen, das Hinzufügen von Bevel sowie die GLB-/BLEND-/FBX-Erzeugung.

Sicherheitsdesign

• Es gibt keine Tools, die beliebiges Blender-Python, Python-Zeichenfolgen, Natursprachenpläne oder Shell-Befehle entgegennehmen.

• Die Brücke ist eine einzige feste blender_mcp_bridge.py, die JSON-Operationstypen/-felder/-werte erneut über eine Allow-List validiert.

• Die Brücke enthält kein eval, exec, subprocess oder die Ausführung externer Befehle.

• Blender wird mit --background --factory-startup --disable-autoexec ausgeführt.

• Es werden subprocess.run(..., shell=False) und ein Argumentarray verwendet, und ein Timeout wird angewendet.

• Eingabedateien werden vor dem Start von Blender auf Existenz und Dateierweiterung geprüft.

• Ausgaben werden nur in Unterordnern mit zufälliger Operations-ID geschrieben; vorhandene Artefakte und Originale werden nicht überschrieben.

• Die Brücke prüft erneut, ob Plan, Ergebnis und Artefakte alle innerhalb derselben Arbeitsordnergrenze liegen.

MVP-Einschränkungen

• Bildtextur-Pixeländerungen, Texture Paint und Baking werden nicht unterstützt.

• Bei Materialien, bei denen eine Textur/ein Node an den Base-Color-Socket angeschlossen ist, kann sich das endgültige Erscheinungsbild auch bei Änderung des Standardwerts nicht ändern. In diesem Fall wird eine Warnung in blender.log geschrieben.

• Materialänderungen unterstützen nur Materialien mit Principled BSDF.

• Modifier: Es werden nur Bevel und Decimate hinzugefügt, nicht angewendet. Wie der Exporter des Exportformats das ausgewertete Ergebnis verarbeitet, folgt dem formatabhängigen Verhalten von Blender.

• Beschädigungen der Blender-Datei selbst, Blender-Importer-/Exporter-Fehler und funktionale Unterschiede zwischen Formaten werden als strukturierte Fehler und Protokolle gemeldet, aber nicht automatisch repariert.

• Jeder Tool-Aufruf startet einen separaten Blender-Prozess, sodass bei großen Assets die Start- und Konvertierungskosten hoch sind.