Blender MCP

Ein Tool, mit dem Claude AI Blender 3D direkt über das MCP (Model Context Protocol) steuern kann.

Wenn Sie Befehle in natürlicher Sprache geben, führt Claude automatisch das Erstellen, Ändern, Löschen von Objekten oder die Ausführung von Python-Code in der Blender-Szene durch.

Funktionsweise

Claude Desktop
     │ MCP (stdio / HTTP·SSE)
     ▼
MCP Server (Python)          ← 이 저장소
     │ TCP Socket :9999
     ▼
Blender Add-on (Python)      ← 이 저장소
     │ bpy API
     ▼
Blender 씬

Related MCP server: BlenderMCP

Anforderungen

Installationsanleitung

Schritt 1 — Repository klonen

git clone https://github.com/nowcika/blender_mcp.git
cd blender_mcp

Schritt 2 — MCP-Server-Abhängigkeiten installieren

pip install -r requirements.txt

Inhalt von requirements.txt: mcp>=1.0.0

Schritt 3 — Blender-Add-on installieren

Zuerst den Ordner addon/ als Zip-Datei komprimieren:

# 터미널에서 프로젝트 루트 위치에서 실행
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

Jetzt in Blender installieren:

1. Klicken Sie im Menü oben im Blender-Fenster auf Bearbeiten (Edit)

2. Klicken Sie auf Einstellungen (Preferences)

3. Klicken Sie links im Einstellungsfenster auf Add-ons

4. Klicken Sie oben rechts auf den Dropdown-Pfeil (⌄) → Von Festplatte installieren (Install from Disk)

5. Wählen Sie die soeben erstellte Datei blender_mcp_addon.zip aus

6. Klicken Sie auf die Schaltfläche Add-on installieren (Install Add-on)

7. Aktivieren Sie das Kontrollkästchen links neben dem Eintrag "Blender MCP", der in der Liste erscheint

Schritt 4 — Socket-Server in Blender starten

Was ist das 3D-Viewport? Wenn Sie Blender öffnen, sehen Sie in der Mitte einen großen 3D-Raum. Dies ist der Hauptarbeitsbereich, in dem Sie Objekte platzieren und bearbeiten. Was ist die Seitenleiste (Sidebar)? Wenn Sie im 3D-Viewport die Taste N auf der Tastatur drücken, öffnet sich rechts ein Panel. Das ist die Seitenleiste.

1. Bewegen Sie den Mauszeiger über den Bereich 3D-Viewport in der Mitte von Blender

2. Drücken Sie die Taste N auf der Tastatur → Die Seitenleiste öffnet sich rechts

3. Klicken Sie auf den Tab MCP oben in der Seitenleiste

4. Klicken Sie auf die Schaltfläche Start MCP Server

5. Sobald sich die Statusanzeige über der Schaltfläche auf Running ändert, ist alles bereit

Wenn die N-Taste nicht funktioniert: Stellen Sie sicher, dass sich der Mauszeiger innerhalb des 3D-Viewports befindet. Blender ändert die Tastenkürzel je nach Mausposition.

Standard-Port: 9999. Zum Ändern die Umgebungsvariable setzen:

BLENDER_MCP_PORT=9998  # Blender 실행 전 설정

Claude Desktop Integration (stdio — empfohlen)

Fügen Sie den folgenden Inhalt zur Datei claude_desktop_config.json hinzu.

Dateipfad:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "blender": {
      "command": "python3",
      "args": ["-m", "server", "--transport", "stdio"],
      "cwd": "/절대경로/blender_mcp"
    }
  }
}

Ersetzen Sie /absoluter/pfad/zu/blender_mcp durch den tatsächlichen Klon-Pfad.
Windows-Beispiel: "cwd": "C:\\Users\\yourname\\blender_mcp"

Starten Sie nach der Konfiguration Claude Desktop neu.

Claude Code (Terminal CLI) Integration

Dies gilt, wenn Sie den claude-Befehl im Terminal anstelle von Claude Desktop verwenden.

Methode 1 — Automatische Erkennung im Projektordner (empfohlen)

Dieses Repository enthält eine .mcp.json-Datei.
Wenn Sie claude innerhalb des Ordners blender_mcp ausführen, wird der MCP-Server automatisch registriert.

cd blender_mcp
claude        # .mcp.json을 자동으로 읽어서 blender MCP 활성화

Methode 2 — Globale Registrierung zur Verwendung von überall

Ersetzen Sie /absoluter/pfad/zu/blender_mcp durch den tatsächlichen Pfad und geben Sie dies im Terminal ein:

claude mcp add --scope user blender python3 /절대경로/blender_mcp/start_server.py

Beispiel (Windows):

claude mcp add --scope user blender python3 C:/Users/yourname/blender_mcp/start_server.py

Registrierung überprüfen:

claude mcp list

HTTP/SSE-Modus (Remote-Zugriff)

Wird verwendet, wenn Sie Blender von einem Remote-Server aus steuern, nicht lokal.

# MCP 서버를 HTTP 모드로 실행
python3 -m server --transport http --host 0.0.0.0 --port 8080

Claude Desktop Konfiguration:

{
  "mcpServers": {
    "blender": {
      "url": "http://서버IP:8080/sse"
    }
  }
}

Verfügbare MCP-Tools

Die folgenden Tools werden automatisch aktiviert, wenn Sie mit Claude chatten.

Anwendungsbeispiel

Im Claude Desktop Chatfenster:

큐브 하나 만들어줘
→ Claude가 create_object 도구 호출 → Blender에 Cube 생성

방금 만든 큐브를 (3, 0, 1)로 이동하고 45도 회전해줘
→ Claude가 modify_object 호출 → 위치·회전 적용

현재 씬에 있는 모든 오브젝트 목록 알려줘
→ Claude가 get_scene_info 호출 → 오브젝트 목록 반환

Umgebungsvariablen

Fehlerbehebung

Fehler "Blender is not running"

• Überprüfen Sie, ob Blender läuft

• Stellen Sie sicher, dass Sie im 3D-Viewport N-Taste → MCP-Tab → Start MCP Server gedrückt haben

• Überprüfen Sie, ob die Firewall den Port 9999 blockiert

Wenn das Add-on nicht in der Liste erscheint

• Überprüfen Sie, ob die Blender-Version 4.2 oder höher ist (überprüfen Sie dies unter Hilfe (Help) → Über Blender (About Blender) oben auf dem Bildschirm)

• Die Dateien im Ordner addon/ müssen sich direkt im Root der Zip-Datei befinden. Komprimieren Sie sie erneut mit der folgenden Methode:

# 올바른 압축 방법 (addon/ 폴더 안에서 실행)
cd addon
zip -r ../blender_mcp_addon.zip .
cd ..

Wenn die Verbindung zum MCP-Server fehlschlägt

# 의존성 확인
pip show mcp

# 서버 직접 테스트 (stdio 대신 로그 확인용)
python3 -m server --transport http --port 8080
# http://localhost:8080/sse 접근해서 응답 확인

Projektstruktur

blender_mcp/
├── addon/
│   ├── __init__.py           # Blender Add-on + 소켓 서버
│   ├── executor.py           # bpy 명령 실행기
│   └── blender_manifest.toml # Blender 5.x Extension 매니페스트
├── server/
│   ├── __init__.py           # MCP 서버 진입점 (stdio / HTTP)
│   ├── tools.py              # MCP 도구 6개 정의
│   └── blender_client.py     # Blender 소켓 클라이언트
├── requirements.txt
└── README.md

Lizenz

GPL-3.0-or-later