# Blender 3d

> Use when working with Blender: MCP, bpy, addons, renders.

- Skill: `wcpaka-lgtm/blender-3d` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add wcpaka-lgtm/blender-3d`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wcpaka-lgtm/blender-3d/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: wcpaka-lgtm (https://skillmd.com/u/wcpaka-lgtm)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/wcpaka-lgtm/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:
```bash
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

```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)

```bash
"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:
  ```python
  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:
```bash
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:

| Task type | Best approach |
|-----------|--------------|
| Low-poly / stylized / geometric | Code-based primitives (works well) |
| Landscape / environment | Code-based vertex displacement (acceptable) |
| Complex character / realistic | **Suggest Hyper3D or Hunyuan3D generation** (text/image → 3D) |
| Hard-surface / mechanical | Code + modifiers (bevel, boolean) |
| Reference-image reproduction | Image → Hunyuan3D `input_image_url` if available |

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