blender-mcp-ultra

MCP server lengkap untuk Blender — 138+ tool, aman, teruji di Blender 4.2 LTS nyata.

Kendalikan Blender dari asisten AI mana pun (Claude, Cursor, Windsurf, opencode) lewat Model Context Protocol (MCP), atau dari chat internal Blender dengan LLM OpenAI-compatible. Seluruh permukaan tool dibangun dari satu spesifikasi (mcp_tools.py) yang melayani FastMCP (SSE) dan bridge STDIO sekaligus.

Demo End-to-End (LLM Nyata → MCP → Blender Headless)

Adegan di bawah dibangun oleh model gpt-5.6-sol melalui API OpenAI-compatible: model memilih 34 aksi tool MCP, dieksekusi lewat socket TCP :9876 ke Blender 4.2.23 LTS blender -b (headless), lalu dirender dengan Cycles.

Yang dikerjakan LLM dalam demo:

• Modeling — create_object (CUBE/CYLINDER/SPHERE/GRID) + transform_object

• Coloring — create_material ×5 (kayu, kaca transmission+ior, logam metallic, lantai, hijau) + assign_material ×5

• Animation — animate_location + animate_rotation (bola, frame 1..120)

• Rigging — create_armature, rig_from_scratch (kursi), add_armature_modifier

• Scene/Render — create_camera, create_light (AREA 300 W), set_render_engine (CYCLES), render_frame

Detail lengkap: DEMO_LLM.md. Jalur verifikasi penuh (70/70 + 66/66 perintah di Blender nyata, socket E2E headless) ada di sana.

Related MCP server: Blender MCP for Antigravity

Fitur

• 138+ tool MCP satu spesifikasi (mcp_tools.py) → FastMCP + STDIO

• Alur "dari nol" per domain: model_from_scratch, colorize_from_scratch, rig_from_scratch, animate_from_scratch

• Modeling data-API aman di blender -b: 12 primitive, 25+ modifier, bmesh (bevel/extrude/inset/loop cut/merge), kurva, teks 3D, screw/lathe

• Coloring: material PBR (Principled BSDF), graf node shader, image texture, vertex color, emisi, transparansi

• Rigging: armature + bone collections (4.0+), IK chain, 20+ constraint, vertex group/weight, auto-rig, pose reset

• Animation: keyframe, animasi loc/rot/scale, action, interpolasi, shape key, rigid body, gravitasi

• Geometry Nodes: modifier, node, scatter instance (4.2+ interface.new_socket)

• UV/Printing/Batch/Analysis/IO: unwrap manual background-safe, manifold, batch rename/delete, ringkasan scene, ekspor 10 format (GLB/FBX/OBJ/USD/…)

• Keamanan: validasi AST, eksekusi dengan timeout + undo, rate limiting

• Multi-provider LLM: OpenAI, Anthropic, Google, DeepSeek, OpenRouter, Ollama

• Verifikasi: 204 tes offline + permukaan penuh di Blender 4.2.23 nyata

Mulai Cepat

Prasyarat

• Python 3.10+

• Blender 4.2 LTS (atau 5.x) — addon memakai bone collections & EEVEE Next

• Klien MCP (Claude Desktop, Cursor, opencode, …)

Pasang addon Blender

# Deteksi otomatis versi Blender, salin paket addon kanonik
python scripts/install.py        # Linux/macOS/Windows
# atau pakai ekstensi .blender_manifest.toml langsung di Preferences > Add-ons

Lalu di Blender: Edit → Preferences → Add-ons → aktifkan "blender-mcp-ultra". Addon membuka socket TCP :9876 (perintah) dan SSE MCP :9879.

Konfigurasi klien MCP

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_mcp.server"],
      "env": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Transport diatur BLENDER_MCP_MODE (stdio default, atau sse untuk :9879).

Uji cepat

pip install -e .
pytest tests/ -q            # 204 lulus offline
python - <<'EOF'
from blender_connection import BlenderConnection
c = BlenderConnection(); c.connect()
print(c.send_command("create_object", {"type": "CUBE", "name": "Tes"}))
print(c.send_command("create_material", {"name": "Merah", "color": [1, 0, 0, 1]}))
EOF

Contoh Tool

Spesifikasi tool datar (bukan namespace bertitik fiktif) — sumber kebenaran di mcp_tools.py:

Semua tool tersedia juga sebagai katalog registry list_tools/describe_tool/ call_registry_tool (dari src/tools/**) dan batch transaksional run_batch.

Chat Internal Blender (LLM)

Aktifkan di panel Axiom: pilih provider (OpenAI/Anthropic/Google/DeepSeek/ OpenRouter/Ollama), isi API key, lalu ketik perintah — mis. "buat meja kayu dan kursi di atas lantai, warna coklat, animasikan mejanya". Asisten memakai search_api_docs() (2.062 dokumen RST) sebelum menulis kode, memvalidasi AST, dan menjalankan dalam undo_push.

Keamanan

• Validasi AST: pola berbahaya (os, subprocess, __import__, dunder) diblokir sebelum eksekusi

• Sandbox: namespace terisolasi + timeout (SIGALRM) + rollback undo

• Rate limiting: token bucket per klien

• Validasi input: pencegahan traversal path, jenis argumen diperiksa

Arsitektur

blender-mcp-ultra/
├── mcp_tools.py          # Spesifikasi tunggal 138 tool (FastMCP + STDIO)
├── mcp_server.py         # FastMCP (SSE :9879 / stdio)
├── blender_connection.py # Klien socket TCP :9876
├── addon/                # Addon Blender (AXIOM): _axsock, handlers, modeling,
│                         #   materials, rigging, animation, scene_tools, ...
├── blender_mcp/          # CLI, rst_search (dokumentasi API lokal), validasi
├── src/tools/            # ToolRegistry ~228 tool (registry bridge)
├── data/api/             # 2.062 RST dokumentasi API Blender
├── scripts/              # install.py (auto-detect versi Blender)
├── skills/               # 19+ skill
├── tests/                # 204 tes offline (stub bpy setia) + e2e
└── demo_artifacts/       # Hasil demo LLM → Blender headless

Verifikasi

Lisensi

MIT