Blender 3D Creation

You build 3D content in Blender by writing Python (via the execute_blender_code tool) against a running Blender instance. Quality bar: the result must actually match the request — not a rough pile of primitives, and not a bare unedited import.

Prerequisite: a live Blender + addon (started for you on first use)

These tools are a thin client: they run Python against a running Blender carrying the blender-mcp addon (bundled in this plugin), and do not launch Blender while serving. Normally you start nothing — just call a tool.

• Default (plugin install): QWEN_MM_AUTOLAUNCH=1 is preset, so the first tool call brings Blender up itself: it auto-installs the pinned Blender 4.2.x if missing (Linux-x86_64, rootless, ~300 MB one-time) and starts it with the bundled addon on $BLENDER_HOST:$BLENDER_PORT (default localhost:9876). Just call a tool such as get_scene_info; the first call may take a minute or two while it downloads (expected), later calls are instant.
• Don't shell out to qwen-mm-plugins-blender --launch-app under a plugin install — that console entry lives inside the uvx environment, not your shell PATH (command not found). Use it only from a source checkout, or for a manual / GUI start:
  Copy code

  python3 src/capabilities/blender/qwen_mm_plugins_blender --launch-app        # headless (xvfb)
  python3 src/capabilities/blender/qwen_mm_plugins_blender --launch-app --gui  # real display
  

Auto-launch can't cover two things: (1) auto-download is Linux-x86_64 only — elsewhere install Blender yourself (apt install blender | brew install --cask blender); (2) a headless box needs a virtual display (apt install xvfb, needs root). If a tool reports it can't connect, it's almost always one of these — the error message spells out which; from a checkout, ... --check-system lists every missing system tool.

Core workflow: build → REFINE → verify (never skip refine)

Generating or importing something is only step 1. A bare import, or a loose pile of assets, is NOT an acceptable final result. Always:

1. Decompose the request into concrete objects, real-world sizes, layout, materials, and lighting.
2. Get base geometry — prefer a generator or a ready-made asset when one genuinely fits. If nothing fits well, build it from scratch (primitives + modifiers + bmesh / geometry nodes); do NOT force an ill-fitting asset just to avoid modeling.
3. Refine deeply to spec — transforms (scale/position/orientation) are the bare minimum, not the goal. A good result usually needs substantial work on top of the base: correct proportions and real-world dimensions; edit/add/remove geometry and fix topology; model the details the request implies; combine/kitbash parts from several sources; author or tune materials and shading (not the defaults); set up lighting; and make objects relate correctly to one another (contact, alignment, consistent scale). Keep going until the object truly looks like what was asked.
4. Verify and iterate — render (bpy.ops.render.render) or capture get_viewport_screenshot, compare against the request, and fix the gaps. Repeat until it genuinely matches. Always call get_scene_info after a task to confirm the changes landed.

Discover what's installed (do this before assuming)

Add-on sets differ per machine — introspect the running Blender instead of guessing:

import bpy
print([a.module for a in bpy.context.preferences.addons])           # enabled add-ons
print([x for x in dir(bpy.ops.mesh) if not x.startswith("__")])     # available mesh operators

Using add-ons

• Operator-based add-ons (Archimesh, A.N.T. Landscape, Tissue, and most add-ons): call the operator directly — operator names (bl_idname) are global and do NOT depend on how the add-on was installed:
  • Architecture (rooms/doors/windows/stairs/kitchen): bpy.ops.mesh.archimesh_room(), .archimesh_door(), .archimesh_window(), .archimesh_stairs(), .archimesh_kitchen()