Lesson 1 · Blender

Control Blender with an AI agent

Direct answer: Run Blender with the community MCP addon, point Claude / Cursor / Codex at uvx blender-mcp, then ask the agent to inspect the scene or write Python. For CI and repeatable exports, skip MCP and call Blender’s official background CLI.

Two ways in, pick one per job

The current community standard is ahujasid/blender-mcp (MIT, blendermcp.org). It is not a Blender Foundation product. It installs two pieces: an addon that opens a socket inside Blender (default port 9876), and a Python MCP server your agent talks to.

Install the live connection

1. Install uv with the official installer, not pip install uv. GUI clients like Cursor do not see a terminal-only PATH.
2. Download addon.py from the repo. In Blender: Edit → Preferences → Add-ons → Install, enable Interface: Blender MCP.
3. In the 3D View press N, open the BlenderMCP tab, click Connect. Leave Poly Haven off until you want remote assets.
4. Register the server in the agent. Claude Code: claude mcp add blender uvx blender-mcp. Cursor / Claude Desktop:

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["--python", "3.11", "blender-mcp"],
      "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
    }
  }
}

On a Mac started from the Dock, replace "command": "uvx" with the full path from which uvx. The README’s common failure is spawn uvx ENOENT.

Do not start uvx blender-mcp yourself in a spare terminal if the client already launches it. Run one server, not two.

What we actually built in Blender 4.3.2

These stills are from a local session on this machine, 13 August 2026. The same operators the installed blender_mcp addon exposes — create primitive, assign material, add light, set camera, render — built a named crate, then a one-room dungeon around it. The MCP socket was started on localhost:9876 during the session.

First prompts that actually work

Ask for inspection before creation. A useful first message:

List every object in the current Blender scene with name, type, location, and polygon count.
Do not create or delete anything yet.

Then a bounded edit:

Create a low-poly crate named Crate_01 at (0, 0, 0.5).
Use a cube, inset the faces, add a wood-colored principled material.
Do not download Poly Haven assets. Save the file when done.

Then freeze the result as a script you can rerun headless:

Write the crate setup as a single Blender Python script I can run with:
blender -b crate.blend -P make_crate.py -- --out crate.glb

Official CLI for the repeatable half

Blender’s own background mode is documented in the command-line arguments manual. -b is background. -P / --python runs a script. --python-expr runs an expression. A game-export job looks like this:

blender -b props.blend --factory-startup -P export_gltf.py -- --out ./public/models/crate.glb

# export_gltf.py
import bpy, sys
out = sys.argv[sys.argv.index('--') + 1]
bpy.ops.export_scene.gltf(filepath=out, export_format='GLB', export_apply=True)
print('exported', out)

That file can feed a Three.js or HTML5 loader. InstantGames games stay 2D Canvas today; the same glTF is still the right hand-off if you later add a 3D prop or a WebGL skin.

Try the workflow on this page

This page cannot start your copy of Blender. It can walk the same checklist an agent should follow: inspect → create one named object → export. Tick a step when you have done it locally. The fake viewport only mirrors the object list so you can see the intended result.

$ blender -b props.blend
# MCP socket not started in this demo

When to use it / when not to

Use MCP while you are exploring. Use the CLI when the steps are known. Do not let the agent call execute_blender_code on an unsaved file. The project README is explicit: that tool runs arbitrary Python inside Blender and can destroy the scene.

How this connects to InstantGames

A 2D Canvas game still needs icons, props, and sometimes a glTF for a WebGL mode. The useful agent loop here is: block out in Blender → export GLB → drop into /games/…/assets. Do not ask the agent to “make the whole HTML5 game in Blender.” Game rules stay in JavaScript, as in the Snake project.