Skip to content

elithril/blender-kiln / plugin

Makes and fixes 3D assets in Blender, for games, the web and AR. Use when the user wants a 3D model, prop, character or GLB/glTF/FBX/USDZ file made — from a text brief, a reference image, a free marketplace (PolyHaven, Sketchfab) or AI generation — AND when they bring an existing 3D file to fix: too heavy or too many polygons (optimize, compress, LODs), broken normals, scale or origin, materials lost on glTF export, conversion between GLB, FBX and USDZ, texturing, rigging for animation, animating it (walk and idle cycles, text-to-motion, looping clips, articulated props), or inspection. Drives Blender through a Blender MCP server (ahujasid's or the official Blender Lab one). Batch mode produces many consistent assets unattended. Kiln Studio (`/kiln studio`) opens the project's models in the browser, where the user reviews them and pins notes for Claude to act on.

FileKindSize
.claude-plugin/plugin.jsonconfig1.2 KB
.mcp.jsonconfig236 B
LICENSEother1.0 KB
NOTICEother2.5 KB
SKILL.mdskill md29.0 KB
references/ai-generation.mdmarkdown21.0 KB
references/animation.mdmarkdown21.6 KB
references/batch-mode.mdmarkdown19.5 KB
references/blender-mcp.mdmarkdown9.4 KB
references/characters.mdmarkdown52.8 KB
references/cli-tools.mdmarkdown6.5 KB
references/commands.mdmarkdown10.7 KB
references/export-targets.mdmarkdown14.3 KB
references/log-format.mdmarkdown2.2 KB
references/naming-conventions.mdmarkdown5.8 KB
references/photo-projection.mdmarkdown6.3 KB
references/pipeline-brief.mdmarkdown4.2 KB
references/pipeline-import-cleanup.mdmarkdown6.3 KB
references/pipeline-optimize-export.mdmarkdown6.4 KB
references/pipeline-rig-animate.mdmarkdown5.8 KB
references/pipeline-source.mdmarkdown9.7 KB
references/print.mdmarkdown41.5 KB
references/reference-fidelity.mdmarkdown31.8 KB
references/review-rounds.mdmarkdown10.4 KB
references/setup-install.mdmarkdown2.8 KB
references/setup.mdmarkdown9.2 KB
references/sourcing-strategy.mdmarkdown6.1 KB
references/studio.mdmarkdown38.9 KB
references/texturing-strategy.mdmarkdown14.4 KB
references/topology-rules.mdmarkdown3.9 KB
references/uv-materials.mdmarkdown6.8 KB
references/validation-checklist.mdmarkdown10.5 KB
studio/approval_hook.pyscript14.2 KB
studio/blender_live.pyscript2.3 KB
studio/checks.pyscript38.1 KB
studio/estimate.pyscript4.2 KB
studio/example/barrel/barrel_final.glbbinary111.9 KB
studio/example/barrel/barrel_log.mdmarkdown445 B
studio/handoff.pyscript17.8 KB
studio/mcp_server.pyscript32.7 KB
studio/phoneshare.pyscript17.1 KB
studio/server.pyscript47.9 KB
studio/setup_status.pyscript7.5 KB
studio/static/app.jsscript241.4 KB
studio/static/apple-touch-icon.pngbinary20.6 KB
studio/static/fonts/OFL-JetBrainsMono.txtmarkdown4.3 KB
studio/static/fonts/OFL-Sora.txtmarkdown4.3 KB
studio/static/fonts/jetbrains-mono-latin-ext.woff2binary11.3 KB
studio/static/fonts/jetbrains-mono-latin.woff2binary30.6 KB
studio/static/fonts/sora-latin-ext.woff2binary11.8 KB
studio/static/fonts/sora-latin.woff2binary24.6 KB
studio/static/i18n.jsscript6.2 KB
studio/static/i18n/fr.jsonconfig101.2 KB
studio/static/icon-32.pngbinary2.6 KB
studio/static/icon-64.pngbinary6.6 KB
studio/static/icon-96.pngbinary12.8 KB
studio/static/index.htmlother39.5 KB
studio/static/style.cssother114.5 KB
studio/static/tutorial.jsscript49.0 KB
studio/static/tutorial/barrel_after.glbbinary117.3 KB
studio/static/tutorial/barrel_before.glbbinary111.9 KB
studio/static/tutorial/fixtures.jsonconfig13.5 KB
studio/static/tutorial/lantern_1_blockout.glbbinary83.1 KB
studio/static/tutorial/lantern_2_details.glbbinary101.8 KB
studio/static/tutorial/lantern_3_materials.glbbinary102.0 KB
studio/static/tutorial/lantern_4_final.glbbinary141.1 KB
studio/static/tutorial/make_tutorial.pyscript4.9 KB
studio/static/viewer.jsscript41.4 KB
studio/studio.pyscript29.2 KB
studio/studiolib.pyscript77.8 KB
studio/test_studio.pyscript90.2 KB
studio/test_worker.pyscript31.5 KB
studio/worker.pyscript56.8 KB
studio/worker_blender.pyscript2.7 KB
tools/autorig.pyscript44.1 KB
tools/bind_rigid_parts.pyscript3.6 KB
tools/blender_mcp_start.pyscript1.5 KB
tools/check_usdz.pyscript1004 B
tools/cutout.swiftscript2.0 KB
tools/export_outputs.pyscript5.2 KB
tools/fidelity_check.pyscript39.0 KB
tools/fit_coupon.pyscript11.3 KB
tools/fixtures/skintokens_raw_child.glbbinary88.8 KB
tools/fixtures/skintokens_skeletons.jsonconfig6.5 KB
tools/flatten.pyscript14.9 KB
tools/glb_to_fbx.pyscript2.1 KB
tools/glb_to_usdz.pyscript6.2 KB
tools/motion_loop.pyscript5.9 KB
tools/motion_measure.pyscript15.2 KB
tools/motions/LICENSE-image-to-3dlab.txtmarkdown11.1 KB
tools/motions/cheer.npzbinary48.4 KB
tools/motions/cheer_b.npzbinary48.1 KB
tools/motions/dance.npzbinary78.2 KB
tools/motions/dance_b.npzbinary78.9 KB
tools/motions/death.npzbinary45.9 KB
tools/motions/death_b.npzbinary46.5 KB
tools/motions/fight_stance.npzbinary60.3 KB
tools/motions/fight_stance_b.npzbinary61.3 KB
tools/motions/flying_kick.npzbinary39.7 KB
tools/motions/flying_kick_b.npzbinary39.9 KB
tools/motions/hit_react.npzbinary31.9 KB
tools/motions/hit_react_b.npzbinary31.8 KB
tools/motions/idle.npzbinary51.8 KB
tools/motions/idle_b.npzbinary57.7 KB
tools/motions/jump.npzbinary39.8 KB
tools/motions/jump_b.npzbinary39.9 KB
tools/motions/kata.npzbinary77.4 KB
tools/motions/kata_b.npzbinary75.3 KB
tools/motions/kick.npzbinary32.4 KB
tools/motions/kick_b.npzbinary32.5 KB
tools/motions/presets.jsonconfig9.6 KB
tools/motions/punch.npzbinary32.0 KB
tools/motions/punch_b.npzbinary32.1 KB
tools/motions/punch_combo.npzbinary47.4 KB
tools/motions/punch_combo_b.npzbinary47.5 KB
tools/motions/roll.npzbinary46.7 KB
tools/motions/roll_b.npzbinary47.5 KB
tools/motions/roundhouse.npzbinary39.7 KB
tools/motions/roundhouse_b.npzbinary39.9 KB
tools/motions/run.npzbinary47.2 KB
tools/motions/run_b.npzbinary47.7 KB
tools/motions/sit.npzbinary47.2 KB
tools/motions/sit_b.npzbinary47.2 KB
tools/motions/sneak.npzbinary61.6 KB
tools/motions/sneak_b.npzbinary61.8 KB
tools/motions/strafe_left.npzbinary45.9 KB
tools/motions/strafe_left_b.npzbinary47.1 KB
tools/motions/sword_swing.npzbinary39.7 KB
tools/motions/sword_swing_b.npzbinary39.4 KB
tools/motions/walk.npzbinary62.8 KB
tools/motions/walk_b.npzbinary62.6 KB
tools/motions/walk_woman.npzbinary62.9 KB
tools/motions/wave.npzbinary46.3 KB
tools/motions/wave_b.npzbinary46.3 KB
tools/open_blender.pyscript5.0 KB
tools/photo_project.pyscript37.8 KB
tools/presets.pyscript16.3 KB
tools/print_check.pyscript47.2 KB
tools/quadruped.pyscript19.4 KB
tools/retarget.pyscript46.9 KB
tools/review_renders.pyscript13.8 KB
tools/review_sheet.pyscript11.0 KB
tools/skintokens-requirements.txtmarkdown2.4 KB
tools/skintokens.patchother9.2 KB
tools/template_profile.pyscript5.8 KB
tools/test_autorig.pyscript15.9 KB
tools/test_fidelity_check.pyscript20.7 KB
tools/test_fit_coupon.pyscript6.4 KB
tools/test_flatten.pyscript15.0 KB
tools/test_open_blender.pyscript1.3 KB
tools/test_photo_project.pyscript12.6 KB
tools/test_presets.pyscript17.6 KB
tools/test_print_check.pyscript33.1 KB
tools/test_review_renders.pyscript11.4 KB
tools/test_review_sheet.pyscript4.0 KB
tools/test_template_profile.pyscript3.6 KB
tools/test_uv_check.pyscript5.0 KB
tools/test_verify_docs.pyexecutablescript7.9 KB
tools/unimate.patchother3.5 KB
tools/unimate.pyscript17.5 KB
tools/uv_check.pyscript8.4 KB
tools/verify_blender.pyexecutablescript29.2 KB
tools/verify_docs.pyexecutablescript16.6 KB

references/blender-mcp.md

View on GitHub
# Blender MCP — tool surface

> Read before the first phase when the Blender MCP is new to the session: kiln runs on three
> tool surfaces, and the rules name the current one. Rule numbers are SKILL.md's Iron Rules.

## Contents
- Which server is this?
- The tools, by need
- mcp-for-blender — what changed, what to know
- On the old surface (mcp-for-blender 2.1.3 and earlier)
- On the official Blender Lab MCP

## Which server is this?

ahujasid's server is **`mcp-for-blender`** (renamed from `blender-mcp` in September 2026;
`blender-mcp` 2.0.0 on PyPI is a shim that installs the latest `mcp-for-blender`, unpinned).
Its tools changed shape in October 2026. Tell the three apart by the tools you have:

| You have | Server | Surface |
|---|---|---|
| `look`, `search_assets` | `mcp-for-blender` **2.1.9 or later** (checked 2.1.9–2.2.2) | current: 9 tools — the names the rules use |
| `get_viewport_screenshot`, `get_object_info` | `mcp-for-blender` 2.1.3 or earlier, `blender-mcp` 1.x | old: 36 tools — the second column below |
| `get_objects_summary`, `get_screenshot_of_area_as_image` | the Blender Lab MCP | § On the official Blender Lab MCP |

## The tools, by need

Read from `mcp-for-blender` 2.2.2's source on 2026-10-21; `look`, `get_scene_info`,
`get_addon_status` and `execute_blender_code` were driven by a bench session the same day.

| Tool (≥ 2.1.9) | Use | Old surface (≤ 2.1.3) |
|---|---|---|
| `get_addon_status` | Rule 23. First call: addon reachable, `up_to_date`, `libraries` and `generators` each `on`/`off` | `get_addon_status()`, then `get_polyhaven_status()` / `get_sketchfab_status()` / `get_polypizza_status()` |
| `get_scene_info` | Rule 1, before each phase. Dimensions (rule 24): `fields=["size", "ground"]` — world bounding box, on / above / below the ground; `query=` or `root=` for one object. Mesh health after cleanup: `fields=["topology", "materials"]` (quads, tris, ngons, non-manifold and boundary edges, loose verts), `weights` for a rig | `get_scene_info()` — names and counts only; dimensions from `get_object_info(name)` → `world_bounding_box` |
| `look` | Rule 2, per phase. `look(mode="angles", target=[name], shading="material")` — framed on the target (rule 22), 1-6 views (front, back, left, right, top, three_quarter, or `[x, y, z]`) in one image; `shading="solid"` for the shape; `mode="frames"` for an animation strip | frame the viewport (PHASE 4's code), then `get_viewport_screenshot()` |
| `execute_blender_code` | Build, clean, export: the workhorse | same |
| `search_assets` | Rule 23 first. `search_assets(source="polyhaven" \| "sketchfab" \| "polypizza", query=…, previews=N)` — results carry each asset's id | `search_polyhaven_assets` / `search_sketchfab_models` / `search_polypizza_models` |
| `import_asset` | Brings a found asset in: `import_asset(source, id, asset_type=…, target_size=…)` sizes it and reports the box; PolyHaven textures with `apply_to=[names]`. Record its licence (rule 17) | `download_polyhaven_asset` / `download_sketchfab_model` / `download_polypizza_model`, `set_texture` |
| `generate_3d` | A model from a generation API — Tripo, Hunyuan3D, Hyper3D, Meshy, or the server's paid Premium: **never by default** (rule 5); kiln's free route is the HF Spaces of `references/ai-generation.md` | `generate_hunyuan3d_model`, `generate_hyper3d_model_via_*`, `generate_tripo_model` and their poll / import tools — same rule |
| `disable_telemetry` | Leave telemetry off; never call `record_trajectory_feedback` | same |

Gone from the current surface, no replacement: `bpy_api_lookup` and `describe_node_type`
(look an API up with `execute_blender_code` — `dir()`, `bl_rna.properties` — rather than from
memory), and `export_scene` (export with `bpy.ops.export_scene.gltf` in `execute_blender_code`,
rules 18 and 19, as kiln always did).

## mcp-for-blender — what changed, what to know

**A library switched off answers in plain words.** `search_assets` on a source whose sidebar
box is unticked returns "Poly Haven is switched off. Ask the user to tick it in the MCP for
Blender sidebar (press N in the 3D Viewport)." Show the user that message — rule 23 — and offer
the other sources or the creation path. `get_addon_status()` says the same up front, in
`libraries`.

**Ticking a box takes effect immediately.** The flags are scene properties read at dispatch
time: no reconnection needed.

**`look` restores what it touches.** Every viewport setting it changes to take the picture is
put back. It frames the target itself in `angles` mode — rule 22 holds without the framing
code; in the default `viewport` mode it shows the viewport as it is aimed, so frame first.
`max_size` defaults to 768: images stay in the conversation, so keep checks small and go larger
only to read fine detail.

**`get_scene_info` measures.** Its `size` is the world bounding box: an axis-aligned box, so a
turned object reads larger than it is — for a print, `print_check`'s dimensions are the
measure, and headless the vertices in world space (rule 24).

**`generate_3d` can cost money.** Each call may use the user's API credits or a monthly
generation; "Premium" is a paid plan. kiln never calls it unasked (rule 5), and never points the
user to Premium.

**`user_prompt`.** Every tool takes the user's own words, for the server's telemetry. Pass the
brief as given, or nothing; telemetry stays off.

**Safe mode breaks kiln.** `BLENDER_MCP_SAFE_MODE=1` (off by default) lets scripts import only
`bpy`, `bmesh`, `mathutils` and pure-Python modules, and refuses `open`, `exec`, `sys`: kiln's
build scripts run through `exec(open(...))` and the live view through `sys.path`. If a script
is refused with "SAFE_MODE is enabled", say so: kiln needs it off, or builds headless (rule 21).

**Check the addon once per session.** `get_addon_status()` reports `up_to_date`; an outdated
addon misses commands. The fix: `uvx mcp-for-blender install-addon`, then disable and enable
"Interface: Blender MCP" in Blender's preferences (or restart Blender) and start the server.

**Two layers, different names.** These are MCP tool names. The addon's raw socket speaks
another vocabulary (`execute_code`), and `get_addon_status` is a server-side aggregation. Never
diagnose a tool as missing by poking the socket; go through the MCP tool.

## On the old surface (mcp-for-blender 2.1.3 and earlier)

Thirty-six tools, one per library and generator — the second column of the table above. Two
things differ in kind:

**A disabled integration does not fail, it disappears.** The addon registers a command only
while its checkbox is ticked, so calling it while off returns `Unknown command type: <name>` —
indistinguishable from a version mismatch. The `get_*_status` tools are always registered and
carry the fix: call them before a search (rule 23), and surface their `message`, never the raw
error. Their remediation text ends with "Restart the connection to Claude": not needed.

**`get_scene_info` carries no dimensions.** Measure with `get_object_info(name)` (rule 24), and
frame the viewport before `get_viewport_screenshot` (rule 22, PHASE 4's code).

`bpy_api_lookup` / `describe_node_type` exist there: look an API or a node's sockets up in the
running Blender rather than recalling it.

## On the official Blender Lab MCP

The Blender Foundation's server (`projects.blender.org/lab/blender_mcp`, the one
behind Claude's Blender connector) drives the same Blender with **different
tools, and none for marketplaces or generation**. Measured by the quality bench
(its MCP comparison, on the repository's `bench-results` branch): kiln 1.1.2 shipped the same 7 GLBs
on it, for 10% less cost. Map the tools, and source around the gaps:

| Rule needs | On the Lab MCP |
|---|---|
| the scene (rule 1) | `get_objects_summary` |
| dimensions (rule 24) | `get_object_detail_summary` |
| a look at the model (rule 2) | `get_screenshot_of_area_as_image(area_ui_type="VIEW_3D")`, or `render_viewport_to_path` |
| framing (rule 22) | `jump_to_view3d_object_by_name` |
| an API looked up | `search_api_docs` / `get_python_api_docs`, plus `search_manual_docs` |
| `execute_blender_code` | same name |
| addon and integration status (rule 23) | none — `get_objects_summary` answering is the connection check |
| PolyHaven | the public API from Bash — `references/sourcing-strategy.md` |
| Sketchfab, Poly Pizza, generation | none — HF Spaces through `gradio_client`, `references/ai-generation.md` |
| export | `bpy.ops.export_scene.gltf` in `execute_blender_code` (rules 18, 19) |

Setup, each point measured: the add-on's manifest sets
`blender_version_min = "5.1.0"` — kiln's own floor stays 4.4, but this path needs
at least that; it installs as an extension; **online access on** (Preferences → System,
or `--online-mode`), or the add-on refuses to serve. Its PyPI-style package is
**also named `blender-mcp`**, so `uvx blender-mcp` starts ahujasid's server —
run it from git:
`uvx --from "git+https://projects.blender.org/lab/blender_mcp.git#subdirectory=mcp" blender-mcp`.
Register it under the MCP name `blender` so `mcp__blender__*` still matches.

**Rule 2 needs saying twice on this server.** The bench's sessions knew the capture
tool and called it right — then took **one screenshot per session** on 4 of 5
briefs, and framed once in five. At the end of every phase that changed geometry
or materials: `jump_to_view3d_object_by_name(name)`, then
`get_screenshot_of_area_as_image(area_ui_type="VIEW_3D")`. After TEXTURING, a second
angle too. A single-asset run therefore takes **at least four** captures.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall