Blender 3d

Blender 3D — AI-Driven Modeling & Automation

When to Use

• User asks to model, sculpt, or create 3D objects in Blender
• Setting up Blender MCP for AI-controlled modeling
• Writing bpy Python scripts (headless or addon)
• Managing Blender addons programmatically
• Rendering scenes via script

Two Approaches to AI Modeling

A. Blender MCP (interactive, real-time control)

Best for iterative modeling where the user watches and steers.

B. Headless bpy scripting (batch, no GUI needed)

blender --background --python script.py — good for parametric/generative work, batch rendering, scene setup. No MCP needed.

MCP Setup (Community: ahujasid/blender-mcp)

Works with Blender 3.0+. Star count 25k+, actively maintained.

Step 1: Deploy addon to Blender

Windows addon path pattern:

%APPDATA%/Blender Foundation/Blender/<VERSION>/scripts/addons/

Download:

ADDON_DIR="$APPDATA/Blender Foundation/Blender/<VERSION>/scripts/addons"
mkdir -p "$ADDON_DIR"
curl -sL "https://raw.githubusercontent.com/ahujasid/blender-mcp/main/addon.py" \
  -o "$ADDON_DIR/blender_mcp_addon.py"

⚠️ Pitfall: Do NOT use MSYS /c/Users/<name>/AppData/Roaming/... literal paths with curl — spaces in "Blender Foundation" break it. Use $APPDATA shell variable instead.

Step 2: Hermes config.yaml

mcp_servers:
  blender:
    command: "uvx"
    args: ["--python", "3.11", "blender-mcp"]
    env:
      UV_PYTHON_PREFERENCE: "only-managed"
      DISABLE_TELEMETRY: "true"

Then restart Hermes for MCP discovery.

Step 3: User activates in Blender

1. Edit → Preferences → Add-ons → search "MCP" → enable checkbox
2. Press N (sidebar) → "Blender MCP" tab → "Start MCP Server" (port 9876)

Verification

After Hermes restart, tools appear as mcp_blender_* (e.g. mcp_blender_execute_blender_code, mcp_blender_get_scene_info).

Blender Official MCP (5.1+ only)

Blender Lab ships an official MCP server: https://projects.blender.org/lab/blender_mcp

• Requires Blender 5.1+
• Addon: drag-and-drop zip into Blender (do it twice: adds repo, then installs)
• More focused on scene analysis, documentation, debugging than creation
• Community addon (ahujasid) is better for generative modeling

Version Upgrade Implications

• Blender does NOT have in-app update — download new installer from blender.org
• Addons live in version-specific folders (4.3/scripts/addons/ vs 5.2/scripts/addons/)
• After upgrading, redeploy addon to new version folder
• Old version can coexist; addon must be in each version's folder separately

Headless bpy Scripting (no MCP needed)

"C:/Program Files/Blender Foundation/Blender 4.3/blender.exe" --background --python script.py

Use for: parametric models, batch operations, rendering, scene assembly. The agent writes the .py, runs it via terminal, checks output/render.

bpy API Pitfalls (5.x)

• obj.shade_flat() does NOT exist as an object method in Blender 5.x. Use the operator instead:

  bpy.ops.object.select_all(action='DESELECT')
  obj.select_set(True)
  bpy.context.view_layer.objects.active = obj
  bpy.ops.object.shade_flat()
  

• Same pattern applies to shade_smooth() — always use bpy.ops.object.shade_smooth().
• After modifying vertices directly, call mesh.update() before shading ops.

Recording / Timelapse

User may ask to record the modeling process. Use ffmpeg gdigrab:

ffmpeg -y -f gdigrab -framerate 15 -i desktop \
  -c:v libx264 -preset ultrafast -crf 28 -pix_fmt yuv420p \
  -t 600 output.mp4

⚠️ Output path must be ASCII-only — Korean/space paths cause "No such file or directory" with ffmpeg on Windows. Use C:/Users/<user>/blender-recording/ then copy to NAS afterward.

Run as background process (terminal background=true) so modeling can proceed simultaneously.

Modeling Workflow — Landscape/Environment

For landscape/environment scenes, this order works well:

1. Clear scene → terrain geometry (plane + subdivide + vertex displacement)
2. Materials per object (Principled BSDF, flat shading)
3. Water features (transparent plane, blend_method='BLEND')
4. Vegetation (parametric functions: make_tree(x,y,z,scale))
5. Rocks/debris (ico_sphere + random vertex jitter + z-squash)
6. Atmosphere (world volume scatter for fog)
7. Lighting (sun with warm color for dawn/dusk)
8. Camera placement + set scene.camera
9. Screenshot via mcp_blender_get_viewport_screenshot to show user

Break into separate execute_blender_code calls per step (MCP timeout safety).

Modeling Workflow — Character/Figure (stylized, figure-style)

For cute/stylized characters (피규어, chibi, Nendoroid-like):

1. Clear scene + materials → display base (transparent glass cylinder)
2. Torso (cylinder + subsurf level 2 for roundness)
3. Head (uv_sphere, scale for proportions, subsurf) + skin material (Subsurface Weight 0.15)
4. Hair (cluster of small uv_spheres with random vertex jitter for curls)
5. Face features (flattened spheres scaled to slit/line shapes, pure black material)
6. Clothing (torus for collar, cube+subsurf for pockets, cylinders for drawstrings)
7. Arms/hands/legs (cylinders + spheres, subsurf, skin or clothing material)
8. Shoes/accessories (cube+subsurf soles, torus straps)
9. Studio lighting: 3-point (key AREA 150W, fill 40W, rim 80W)
10. Camera: 50mm lens, portrait orientation (1080×1920)
11. Render: Cycles, 128 samples, denoising on

Key techniques:

• Skin: Principled BSDF + Subsurface Weight 0.15 + Subsurface Radius (1.0, 0.2, 0.1)
• Fabric (fleece/hoodie): Noise Texture (Scale 30) → Bump (Strength 0.3) → Normal input
• Glass base: Alpha 0.3, blend_method='BLEND', IOR 1.45, Roughness 0.05
• Proportions: head ≈ 40% of total height for chibi; big head + stubby limbs
• Group parts logically but keep as separate objects (easier to adjust)

Recording / Timelapse (timing)

⚠️ Start ffmpeg BEFORE modeling begins — not after. The user wants the full creative process captured. If you start recording after the model is done, you only get a static screen. Sequence:

1. Launch ffmpeg background process first
2. Verify it's running (poll for frame output)
3. THEN begin modeling steps
4. Kill/let-expire ffmpeg when done

Quality Expectations & Tool Selection

User found pure-primitive-assembly modeling "too amateurish" (모델링 너무 별로다). Be honest about limitations and choose the right approach:

When the user provides a reference image for a character, first offer AI-generation (Hyper3D/Hunyuan3D) before falling back to primitive assembly. Primitive assembly is a fallback, not the default for characters.

If generation tools aren't enabled (checkboxes unchecked in addon), tell the user and offer to enable them.

User Preferences (this user)

• Wants AI to design the creative concept/prompt, not just execute instructions
• Asks for recording of the modeling process (timelapse)
• Prefers step-by-step visible progress with screenshots between stages
• Korean language interaction
• High quality bar — found primitive-assembly characters unacceptable. Always aim for the best achievable quality and be upfront about limitations before starting
• Prefers to be told "this approach will look basic" BEFORE spending time on it, rather than being disappointed after

Pitfalls

• First MCP command after connection sometimes fails silently — retry once
• Complex operations should be broken into smaller steps (MCP timeout)
• execute_blender_code runs arbitrary Python in Blender — save work first
• Poly Haven / Sketchfab features need API keys in addon preferences
• On Windows, uvx path may not be inherited by GUI-launched apps — use full path in config if spawn uvx ENOENT occurs

References

• See references/mcp-config-snippets.md for ready-to-paste config blocks