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.

Frame 1 — meja kayu, vas kaca, bola logam, kursi hijau, lantai	Frame 60 — bola teranimasi (lokasi + rotasi)	Sudut kamera kedua

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.

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:

Domain	Tool
Modeling	create_object, transform_object, duplicate_object, join_objects, add_modifier, subdivide_mesh, loop_cut, extrude_face, inset_face, merge_by_distance, clean_mesh, create_text, create_curve, create_screw_profile, model_from_scratch
Coloring	create_material, assign_material, set_color, set_emission, set_transparency, add_shader_node, connect_shader_nodes, set_node_value, create_image_texture, assign_image_texture, add_vertex_color, colorize_from_scratch
Animation	insert_keyframe, keyframe_animation, animate_location, animate_rotation, animate_scale, set_keyframe_interpolation, create_action, add_shape_key, add_rigid_body, set_gravity, set_render_range, animate_from_scratch
Rigging	create_armature, add_bone, mirror_bones, setup_ik_chain, add_constraint, add_vertex_group, assign_vertex_weights, auto_rig_weight, add_armature_modifier, reset_pose, rig_from_scratch
Geometry Nodes	add_geometry_nodes_modifier, gn_add_node, scatter_instances, list_gn_modifiers
Scene/Render	create_camera, set_camera_target, create_light, setup_three_point_lighting, set_render_engine, set_render_samples, set_render_resolution, set_cycles_device, render_frame, scene_summary, scene_graph, align_objects, measure, find_objects
UV/Texture	add_uv_map, unwrap_object, list_uv_maps, texel_density
Batch/Analysis	batch_rename, batch_delete_by_type, apply_transforms_all, mesh_analysis, get_objects_summary, get_object_detail_summary
Printing	check_manifold, set_dimensions_mm, add_wall_thickness
IO	export_scene, export_selected, import_file, list_export_formats

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

Lapisan	Hasil
Tes offline (pytest tests/)	204 lulus, 105 skip (butuh binary Blender)
Blender 4.2.23 nyata — perintah inti	70/70 + 1 UI-only skip
Blender 4.2.23 nyata — permukaan diperluas	66/66 + 1 UI-only skip
Socket E2E headless (TCP :9876)	ping, scene, create, material, animasi, workflow
Demo LLM (gpt-5.6-sol)	34 aksi → 3 render Cycles

Lisensi

MIT