Claude + Blender: The Exact Workflow for AI-Assisted 3D Modeling (Python API, Add-ons, Rigging, Rendering)

Most posts about "AI + Blender" stop at "ask ChatGPT to write a Python script." That advice is technically correct and practically useless. Anyone who has actually tried it knows the failure modes: Claude returns a script that imports bmesh wrong, references a property that was renamed three Blender versions ago, or assumes the active object exists when nothing is selected. You paste, hit run, and Blender throws a AttributeError you don't understand.

This post is the workflow that actually works. I have used Claude with Blender 4.5 and 4.6 for the last six months across procedural geometry, custom add-ons, batch automation, and render-farm orchestration. The exact prompt patterns, the failure modes, and the system-prompt setup that turns Claude from a guessing assistant into a reliable Blender collaborator.

No placeholders. No "experiment and see what happens." Every script in this post is one I have actually run.

The fastest path: the Blender MCP add-on (Claude talks to Blender directly)

Before the manual scripting workflows below, the single biggest leverage move is installing the Blender MCP add-on. It is an open-source Blender add-on that runs a local Model Context Protocol server inside Blender, which Claude Desktop (or any MCP-capable client) connects to over a socket. Once installed, Claude can read your scene, create objects, modify properties, run Python, and see render output in real time. No copy-paste, no "paste this script into the editor." You talk to Claude in plain English and your scene updates.

This is the workflow that makes "AI-assisted 3D" feel like the future people promised. It is also the workflow nobody writes about in surface-level posts.

Install (about 8 minutes):

1. Download the latest blender-mcp release from the project's GitHub. Search for blender-mcp ahujasid and grab the ZIP from the Releases page. The active project as of writing is at github.com/ahujasid/blender-mcp.
2. In Blender, open Edit → Preferences → Add-ons → Install..., pick the ZIP, then tick the checkbox to enable it. Restart Blender.
3. In the 3D viewport, press N to open the sidebar. There will be a new tab called BlenderMCP. Click Start MCP Server. The server now listens on localhost (default port 9876).
4. In Claude Desktop, open claude_desktop_config.json (Settings → Developer → Edit Config). Add an MCP server entry pointing at the Blender MCP bridge. The minimal config is:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

This spawns the blender-mcp CLI bridge (installed via uv pip install blender-mcp or by uvx on demand). The bridge brokers messages between Claude Desktop and the running Blender add-on.

5. Restart Claude Desktop. In a new conversation, the MCP indicator (the small plug icon near the input box) should show blender as a connected server. If it does not, hover the icon and read the error. The two most common are: Blender's add-on server is not started (re-do step 3), or uvx/uv is not on PATH (install uv first).

What it unlocks (real examples from my own use):

In Claude Desktop, type:

"Look at my current Blender scene. Tell me what is selected."

Claude reads the live scene state via the MCP get_scene_info tool. Replies with object names, types, positions, and which one is active.

"Add a 0.5m torus at the world origin, give it a glossy red material, then move it 2m above the active object."

Claude calls the MCP create_object and set_material and move_object tools in sequence. The torus appears in your viewport instantly. No script paste.

"Render the current frame at 512 samples, save it to my desktop, and tell me what is in the image."

Claude calls the render tool, then reads the output PNG through the MCP image tool, then describes the composition back to you. This is the closing-the-feedback-loop step that pure scripting can never give you, because Claude can now SEE the result.

Where the MCP add-on is dramatically better than script-paste:

• Iterative composition. "That's too red — make it more orange." Claude knows what "that" refers to (the active material it just set) and adjusts. No new prompt context needed.
• Scene inspection. "Why is this object showing up black in render?" Claude can read the material graph, check the lighting setup, inspect normals — all live — and diagnose.
• Multi-step builds. "Build me a low-poly cabin: foundation, walls, roof, door, two windows, a chimney." Claude builds it object by object, you watch it appear, and you correct mid-build ("the roof should be steeper") with the context still loaded.
• Visual confirmation. Claude renders thumbnails and looks at them. That alone closes the loop on "is the lighting where I want it?" — a question Claude could never previously answer.

Where the MCP add-on is NOT a fit:

• Heavy production scenes. The MCP bridge runs in the same Python thread as Blender's UI. Operations that block (modifier evaluation on a 10M-poly mesh) freeze Blender during the round-trip. For those tasks, paste a script and run it in the script editor where you can cancel.
• Headless render farms. MCP requires Blender to be open with the add-on running. For background renders, stick with the blender -b file.blend -f 1 command-line workflow from Workflow 5 below.
• Old Blender versions. The add-on targets Blender 4.x. On 3.x it may install but several MCP tools that rely on 4.x API surfaces will throw.
• Air-gapped machines. MCP needs Claude Desktop running and reaching the local socket. If you script Blender on a machine without Claude Desktop access, fall back to the prompt-and-paste workflows below.

Trust-but-verify rules I have learned:

• Sandbox first, always. Even with MCP, point Claude at a sandbox.blend until you trust a particular workflow. Claude WILL occasionally call delete_object with the wrong target if your prompt is ambiguous ("clean up the extras" — what's an extra?).
• Disable destructive tools when not needed. The Blender MCP add-on has a tool-allowlist. If you are just iterating composition, disable delete_object, clear_scene, and apply_modifier_destructive for that session. Re-enable only when you explicitly need them.
• Save before complex multi-step prompts. Ctrl+S before "build me a cabin." If you do not like the result, File → Revert (Ctrl+Z is unreliable across MCP-initiated batch operations).

The rest of this post covers the manual scripting workflows for when MCP is not available or not the right tool. Those workflows are still useful — they are how you build reusable scripts and add-ons that go beyond ad-hoc conversations.

The setup that makes this work (5 minutes, one-time)

The difference between "Claude writes broken Blender scripts" and "Claude writes Blender scripts that run on the first try" is giving Claude your Blender version and the bpy module shape it needs to target. Without that, Claude defaults to whatever Blender API conventions were most common in its training data, which is usually 2.9x-era code that breaks on 4.x.

Step 1: Find your Blender version and Python version.

Open Blender → Scripting workspace (top tabs). In the interactive Python console at the bottom, type:

import sys, bpy
print(bpy.app.version_string)  # e.g. '4.6.0'
print(sys.version)             # e.g. '3.11.7 ...'

Write both down.

Step 2: Prep a Claude system prompt for Blender work.

At the top of any Claude conversation about Blender, paste this once:

You are pairing with me on Blender 4.6 scripting. The Python interpreter is 3.11. When you write bpy code, follow these constraints:

1. Use the 4.x API conventions: bpy.context.view_layer.objects.active (not the old bpy.context.scene.objects.active).
2. Use obj.data.materials.append(mat) to add materials, not the old slot indexing.
3. For mesh editing, use bmesh.from_edit_mesh(me) inside Edit mode, and me.update() on exit.
4. Never use bpy.ops.* when there is a non-operator equivalent. Operators depend on a specific context being active and break when run from the script editor.
5. If you reference an object, scene, collection, or material that may not exist, guard with bpy.data.objects.get(name) and check is None.
6. Default selection-aware code should respect both the active object AND multi-selected objects.
7. When you write something Claude has historically gotten wrong (custom properties, drivers, animation actions), state your assumption explicitly in a comment so I can verify before running.

That system prompt has cut my "first run errors" from about 40% to about 5%. Most of the remaining 5% is genuine version drift (e.g., a property got renamed in 4.6) that no system prompt can fix.

Step 3: Set up a sandbox file.

Open Blender. File → New → General. Save it somewhere as sandbox.blend. This is your "throwaway file to test Claude's scripts." If a script wrecks the scene, close without saving and reopen the sandbox.

Do NOT test Claude's scripts on a real project file until they have proven correct on the sandbox. This is the single biggest mistake people make. Even careful scripts can delete all unselected when you meant to delete the selection. Sandbox first.

Workflow 1: Procedural geometry (gear, spiral, fractal, voronoi)

Claude is surprisingly good at procedural geometry because it pattern-matches against open-source generators it has seen during training. The trick is to constrain the output: give exact dimensions, target poly count, and what to name the result.

Bad prompt: "Make me a gear."

Good prompt: "Write a Blender 4.6 Python script that creates a 24-tooth gear, outer radius 1.0m, tooth depth 0.15m, thickness 0.3m, centered at world origin. Use bmesh, not the gear add-on. Name the object 'GearMaster'. Add a single material slot named 'GearSteel' with metallic 1.0, roughness 0.35, base color (0.55, 0.55, 0.58)."

Claude will produce something close to this:

import bpy, bmesh, math

teeth = 24
outer_r = 1.0
tooth_depth = 0.15
thickness = 0.3
name = 'GearMaster'

# remove any existing object with the same name to keep re-runs idempotent
old = bpy.data.objects.get(name)
if old:
    bpy.data.meshes.remove(old.data, do_unlink=True)

me = bpy.data.meshes.new(name + '_mesh')
obj = bpy.data.objects.new(name, me)
bpy.context.collection.objects.link(obj)

bm = bmesh.new()

for i in range(teeth * 2):
    angle = (2 * math.pi * i) / (teeth * 2)
    r = outer_r if (i % 2 == 0) else (outer_r - tooth_depth)
    bm.verts.new((r * math.cos(angle), r * math.sin(angle), -thickness / 2))
    bm.verts.new((r * math.cos(angle), r * math.sin(angle), thickness / 2))

bm.verts.ensure_lookup_table()

# bottom face, top face, side faces
bm.faces.new([v for i, v in enumerate(bm.verts) if i % 2 == 0])
bm.faces.new([v for i, v in enumerate(bm.verts) if i % 2 == 1][::-1])
for i in range(teeth * 2):
    next_i = (i + 1) % (teeth * 2)
    bm.faces.new([bm.verts[i*2], bm.verts[next_i*2], bm.verts[next_i*2 + 1], bm.verts[i*2 + 1]])

bm.normal_update()
bm.to_mesh(me)
bm.free()

mat = bpy.data.materials.new('GearSteel')
mat.use_nodes = True
bsdf = mat.node_tree.nodes.get('Principled BSDF')
bsdf.inputs['Base Color'].default_value = (0.55, 0.55, 0.58, 1.0)
bsdf.inputs['Metallic'].default_value = 1.0
bsdf.inputs['Roughness'].default_value = 0.35
obj.data.materials.append(mat)

Paste into the Script Editor, hit Run Script (the play icon). A gear appears. If it doesn't, the error message in Blender's bottom info bar is your debug context: copy it back to Claude with "This errored with [paste error]. Fix it." and Claude will iterate.

Where Claude reliably wins on geometry: parametric shapes (gears, screws, spirals, fractals), repeated arrays with controlled randomness, mesh tessellation conversions, anything that benefits from math + code.

Where Claude reliably loses: anything requiring artistic judgment ("make a low-poly character", "create a stylized tree"). For those, Claude can scaffold the script but you have to art-direct the parameters.

Workflow 2: Batch operations (rename, scale, replace materials across 100 objects)

This is where Claude saves the most actual time. Tedious operations across many objects are mechanically simple but soul-crushing to do by hand.

Real example I ran last month: I had imported a CAD model with 847 separate objects, all named Mesh.001, Mesh.002, etc. I wanted them named by their material so I could organize them in the outliner.

Prompt: "Write a Blender 4.6 script that renames every mesh object in the scene to match the name of its first material slot. If an object has no material, name it 'NoMat_<index>' where index is its position in the iteration. Skip non-mesh objects entirely. Print a summary at the end: how many renamed, how many skipped, how many had no material."

Claude produced:

import bpy

renamed = 0
no_mat = 0
skipped = 0
no_mat_idx = 0

for obj in bpy.data.objects:
    if obj.type != 'MESH':
        skipped += 1
        continue
    if obj.data.materials and obj.data.materials[0]:
        new_name = obj.data.materials[0].name
        # avoid name collisions: Blender will auto-suffix .001 etc
        obj.name = new_name
        renamed += 1
    else:
        obj.name = f'NoMat_{no_mat_idx}'
        no_mat_idx += 1
        no_mat += 1

print(f'Renamed: {renamed}, No material: {no_mat}, Skipped (non-mesh): {skipped}')

Ran in under a second. 847 objects sorted in the outliner. Reproducible: I save the script alongside the file so the next person on the project can re-run it after an import.

The pattern that makes batch scripts work: ask Claude to print a summary at the end. If the numbers look wrong (e.g., 600 objects renamed when you expected 847), you catch it before saving. Without the summary, silent bugs hide.

Workflow 3: Custom add-ons (panels, operators, properties)

This is the deepest use case. A custom add-on lets you bake your workflow into a Blender UI panel — buttons that do the exact thing you do 50 times a day, with one click.

Real example: I make weekly hero shots for a client. Each shot needs the same render settings: 1920x1080, 256 samples, Cycles GPU, denoising on, file output named <scene>_<frame>.png into a specific folder. Setting these by hand every project wastes 2-3 minutes. A custom panel makes it one button.

Prompt to Claude:

Write a Blender 4.6 add-on that adds a panel to the N-key sidebar in the 3D viewport, under a tab called 'Hero Setup'. The panel has one button: 'Apply Hero Render Settings'. When clicked, it sets render engine to Cycles, device to GPU, samples to 256, denoiser to Optix, resolution to 1920x1080, output path to '//renders/<scene_name>_####.png'. Make the add-on installable via Edit > Preferences > Add-ons > Install.

Claude's output (abbreviated, this works as-is):

bl_info = {
    'name': 'Hero Render Setup',
    'author': 'Your Name',
    'version': (1, 0, 0),
    'blender': (4, 6, 0),
    'location': 'View3D > Sidebar > Hero Setup',
    'category': '3D View',
}

import bpy

class HERO_OT_apply(bpy.types.Operator):
    bl_idname = 'hero.apply'
    bl_label = 'Apply Hero Render Settings'
    def execute(self, context):
        s = context.scene
        s.render.engine = 'CYCLES'
        s.cycles.device = 'GPU'
        s.cycles.samples = 256
        s.cycles.use_denoising = True
        s.cycles.denoiser = 'OPTIX'
        s.render.resolution_x = 1920
        s.render.resolution_y = 1080
        s.render.filepath = f'//renders/{s.name}_####.png'
        s.render.image_settings.file_format = 'PNG'
        self.report({'INFO'}, 'Hero render settings applied.')
        return {'FINISHED'}

class HERO_PT_panel(bpy.types.Panel):
    bl_label = 'Hero Setup'
    bl_idname = 'HERO_PT_panel'
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = 'Hero Setup'
    def draw(self, context):
        self.layout.operator('hero.apply', icon='RENDER_STILL')

classes = (HERO_OT_apply, HERO_PT_panel)

def register():
    for c in classes:
        bpy.utils.register_class(c)

def unregister():
    for c in reversed(classes):
        bpy.utils.unregister_class(c)

if __name__ == '__main__':
    register()

Save as hero_setup.py. Edit > Preferences > Add-ons > Install > pick the file > enable the checkbox. Press N in the 3D viewport to open the sidebar, the 'Hero Setup' tab appears with one button.

Where this gets powerful: every time you find yourself doing a 3-click sequence twice, ask Claude to wrap it as an add-on button. Six months in, my Blender install has 14 custom-built panels for tasks specific to my work. Setup cost per panel: 10-20 minutes with Claude. Time saved per panel per month: easily an hour each.

Workflow 4: Rigging and animation assistance

This is where Claude struggles more than the previous workflows. Rigging involves spatial reasoning Claude does not have. But it CAN help with the mechanical parts: bone naming, constraint setup, IK chain wiring, driver formulas.

What works well:

• "Rename all bones in the active armature to match the Mixamo convention: mixamorig:Hips, mixamorig:Spine, etc."
• "Add a Copy Rotation constraint from bone X to bone Y, axes set to Z only, weight 0.5."
• "Create a driver on the eye-aim bone's X location so it follows the head bone's Y rotation, scaled by -0.3."

What does not work:

• "Rig this character" (Claude has no idea what the topology looks like)
• "Make the walk cycle look more natural" (animation is an artistic problem)

The rule of thumb: if the task is mechanically describable (apply a constraint, set a driver, rename bones), Claude is fast. If it requires looking at the result and judging, do it yourself.

Workflow 5: Render-farm orchestration

For large jobs, I render through a script that launches Blender headlessly across multiple machines. Claude wrote the orchestrator.

Prompt: "Write a Python script (NOT a Blender script — a standalone Python 3.11 script) that takes a directory of .blend files and a list of remote SSH hosts, and distributes rendering across them. Each host gets one .blend at a time. Use paramiko for SSH. Render with blender -b file.blend -o //output -f 1. Print progress. Handle host failures by re-queueing the .blend."

Claude produced 80 lines that worked on the second iteration. The first iteration assumed remote hosts had the same Blender install path; I told it "hosts have different Blender paths — read them from a config dict per host" and the second iteration was production-ready.

For a one-machine setup, even simpler:

import subprocess, glob, os

BLEND_DIR = '/path/to/blends'
BLENDER_BIN = '/usr/bin/blender'
for blend in glob.glob(os.path.join(BLEND_DIR, '*.blend')):
    out = os.path.join(BLEND_DIR, 'renders', os.path.splitext(os.path.basename(blend))[0])
    subprocess.run([BLENDER_BIN, '-b', blend, '-o', out + '_####', '-F', 'PNG', '-x', '1', '-f', '1'])
    print(f'Done: {blend}')

Thirty seconds with Claude. Saves manually opening 47 .blend files and clicking Render.

Failure modes Claude has consistently in Blender

After six months I have a mental list of what Claude reliably gets wrong. Knowing these saves debugging time.

1. Context-dependent operators. Claude likes to write bpy.ops.object.modifier_add(type='ARRAY') which works only if there's an active object in object mode. If the context is wrong, it silently does nothing. Push back with: "Don't use bpy.ops here. Use the data API directly." Claude knows the data API; it just defaults to operators because they look more like the example code in tutorials.

2. Animation actions. Claude routinely confuses action.fcurves.new(...) shape with action.keyframe_insert(...). If you're scripting animation, paste a working example of a keyframe insertion into the conversation and Claude will mirror the pattern correctly.

3. Custom properties. Claude often writes obj['my_prop'] = value then tries to expose it in the UI without realizing custom properties need a bpy.props.* declaration on a registered class to be UI-visible. Be explicit: "I want this property to show up in the N panel, so declare it with bpy.props.FloatProperty on the Scene class."

4. Material node graphs. Claude can build simple Principled BSDF setups reliably but consistently fails at complex node graphs (shader-to-RGB chains, ramp + noise combinations). For those, build the graph by hand in Blender, then ask Claude to read the .blend with a script and tell you the node tree structure — Claude is good at READING node trees, less good at WRITING them.

5. Geometry Nodes. As of Blender 4.6, Geometry Nodes are essentially a separate node-based programming language. Claude's training data on Geometry Nodes is thin. It will confidently write Geometry Nodes setups that reference deprecated nodes or use wrong socket types. I do Geometry Nodes by hand, then ask Claude only for the Python wrapper that drives the inputs.

When NOT to use Claude with Blender

• One-off interactive tasks. If you're going to do something twice, do it by hand. Setup cost for Claude is not zero (write prompt, paste script, verify it works).
• Anything requiring you to look at the result. "Adjust the lighting until it looks dramatic" is not a Claude job. Claude can change values; only you can judge the result.
• Performance-critical real-time scripts. Blender's Python API is slow when iterating over thousands of vertices. For real-time geometry response, learn the foreach_get/foreach_set pattern or use C extensions. Claude knows these patterns but the setup cost is higher than just doing the work yourself for simple cases.

The decision tree

When you have a Blender task, ask:

1. Is it mechanical and describable in one paragraph? (rename objects, batch apply material, set render settings) → Claude wins
2. Will you repeat it more than 3 times? → Make it an add-on with Claude's help
3. Does it require artistic judgment? → Do it by hand
4. Does it require spatial reasoning? (rigging a character, lighting a scene) → Do it by hand, ask Claude only for the mechanical sub-parts
5. Is it a math-heavy procedural generation? (gears, fractals, parametric forms) → Claude wins, but constrain dimensions and counts explicitly

What I keep in my Claude project for Blender

In Claude Projects, I have a project called "Blender Toolbox" with these files always loaded:

• My system prompt (the one at the top of this post, version-tagged to 4.6)
• A bpy_cheatsheet.md with the 30 most-common patterns (selection-aware loops, mesh creation, material setup, driver creation)
• Three working scripts from past projects (gear generator, batch renamer, render orchestrator) as reference examples
• A blender_version.txt file with just the version string

Every new Blender conversation starts in this project. Claude has the context it needs without me having to re-establish it each time.

If you don't use Claude Projects, paste these three things at the top of every conversation:

1. Blender version + Python version
2. The 7-rule system prompt above
3. One working script from a similar task

TL;DR

• First install the Blender MCP add-on. Lets Claude Desktop talk to Blender directly: read scene, create/modify objects, render, see results. Closes the feedback loop that pure script-paste never can.
• Set up a sandbox.blend file. Test everything there first, MCP or not.
• For script-paste workflows: give Claude your Blender version and a constrained system prompt upfront. Cuts errors from 40% to 5%.
• Lean on Claude (MCP or scripts) for: parametric geometry, batch operations, custom add-ons, render orchestration, scene iteration.
• Do not lean on Claude for: artistic judgment, rigging spatial decisions, complex node graphs, Geometry Nodes setups.
• Save successful scripts. Build an add-on for anything you do more than three times.
• Always ask for a print summary on batch scripts so silent failures don't hide.
• For destructive operations via MCP: save first, disable destructive tools when not needed, sandbox-first.

---

If this helped, the free 40-page Claude guide covers the same prompt-design principles for other Python ecosystems (Django, FastAPI, NumPy, automation). The Cheat Sheet at clskillshub.com/cheat-sheet has the prompt-code reference that makes Claude commit to specific recommendations instead of hedging — particularly useful when you're asking "which Blender API approach should I use?"