BlenderLens

BlenderLens: game assets built, checked and exported by Blender itself

[GitHub Release] [npm] [PyPI] [License: Apache 2.0]

An MCP server that lets an AI agent work in Blender itself: build and shape objects with Blender's own operations, look at a rendered preview, check the asset against a triangle budget and your project's rules, and export a .glb that is read back from disk and judged for Godot or three.js.

[Two teddy bears in a forest: one picks a flower and gives it to the other, and they walk off together]

A short animated scene that an AI agent made in Blender through BlenderLens, shown at double speed.

Why

An agent that models through Blender Python is working blind. It cannot see what it built, cannot tell whether the exported file holds what it meant, and learns about a part that did not export, or an import hint it never intended, only when the game shows it.

BlenderLens never judges an asset from what the agent intended. It asks Blender, and the written file. Measured on Blender 5.0.1, on a scene with a 0.5 m crate, a lid named Lid_col parented to it, and a metaball:

That principle, ask Blender and the file, never assume, runs through every tool. The building tools return what Blender now holds. render_preview renders the scene with Blender. check_asset reads the mesh as the exporter will write it. export_glb reads back the file it wrote.

Requirements

Blender 4.2 is the floor because it is the oldest LTS release with the extension system the add-on installs through. An older Blender is refused with a clear message. No GPU is needed: previews and bakes render with Cycles on the CPU.

Install

npx (recommended). The package bundles the server, and needs Python 3.10 or later on PATH.

{  "mcpServers": {    "blenderlens": {      "command": "npx",      "args": ["-y", "blenderlens-mcp"],      "env": { "BLENDER_BIN": "C:\\Program Files\\Blender Foundation\\Blender 5.0\\blender.exe" }    }  }}

pip

pip install blenderlens-mcp

{  "mcpServers": {    "blenderlens": { "command": "blenderlens-mcp", "env": { "BLENDER_BIN": "/path/to/blender" } }  }}

In Claude Code this goes in a project's .mcp.json. That is all a headless pipeline needs: the first call that needs Blender starts blender --background, and the server keeps it until the server exits.

Watching it work in Blender

To have the agent work in a Blender window you watch, and can undo, install the add-on:

blenderlens-mcp install-addon       # or: npx -y blenderlens-mcp install-addon; --blender PATH picks the Blender

Then, in the 3D viewport, press N, open the BlenderLens tab and press Start. The add-on listens on this machine only, and serves only a server that holds its token, which it writes to a file the server reads.

The loop

The tools are designed around one cycle. Read it once and the rest of this document is a reference.

flowchart LR    B["<b>Build</b><br/>create_object<br/>edit_mesh<br/>set_material"]    L["<b>Look</b><br/>render_preview<br/>get_object"]    C["<b>Check</b><br/>check_asset<br/>measure_objects"]    D["<b>Deliver</b><br/>export_glb<br/>save_file"]
    B --> L --> C --> D    L -- "not right yet" --> B    C -- "an issue" --> B
    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;    class B,L,C,D step;

1. Build. create_object makes a part with its size built into the mesh, edit_mesh shapes it, set_material colours it, and join_objects and set_parent assemble parts. An existing build script runs as it is with run_script.
2. Look. render_preview renders the part, or a sheet of several angles, as a PNG to look at. get_object gives exact sizes and counts.
3. Check. check_asset finds broken geometry, unapplied scale, a misplaced origin, UV and texture problems, parts passing through each other, and anything over budget or against your rules, each with the faces concerned. measure_objects says what touches what.
4. Deliver. export_glb writes the file for your target engine, reads it back and warns. save_file keeps the .blend.

Three conventions apply throughout:

• Units are metres, rotations degrees, and Z is up. A model's front faces -Y; export_glb converts to glTF's Y-up, where the front faces +Z.
• Face indices are what get_mesh lists, and change after any edit that adds or removes faces. edit_mesh returns the faces it made.
• A refusal changes nothing. It is a structured error with error, exit, kind and hint. The kinds, with their exit codes: blender_error 1, not_found 2, bad_argument 3, python_error 4, unsaved_changes 5, blender_missing 6, not_connected 7, connection_lost 8, start_failed 9, version_mismatch 10, token_mismatch 11, busy 12, not_allowed 13, internal_error 70, deadline 124.

Tools

Session

Inspecting

Building

Arranging

Checking

Seeing

Files

Python and undo

Checking in CI

blenderlens-mcp check runs the same checks from the command line, with no agent. It exits 0 when the asset passes, 1 when it fails, and 2 when it could not be checked; --json prints the full result. A .glb is read on its own, with no Blender; a .blend is opened in a background Blender.

blenderlens-mcp check crate.glb --budget 2000 --target godot --rules rules.json

A project's rules are a JSON object. Each key is optional:

A name may also be a pattern, "re:<regular expression>". examples/rules.json is a complete rule set, and examples/build_lantern.py builds, checks and exports a prop through the server from start to finish.

What Blender cannot tell you

Worth knowing before you trust a result:

• Python is unrestricted. run_python and run_script can do anything Python can inside Blender, including quitting it. Set BLENDERLENS_ALLOW_PYTHON=0, or turn off Allow Python from the agent in the add-on, where that matters.
• Blender's glTF exporter writes a metaball as an empty node. check_asset reports metaballs as errors, and export_glb warns about them.
• drop finds supports at vertices. When the only contact would be edge against edge, such as one bar lying across another, that support is missed and the object drops past it.
• A Principled BSDF inside a node group is invisible to BlenderLens, so it will not change that material's values.
• In a Blender window, a preview marks the file as changed, because Blender does so whenever the render engine is set, even back to the same one.
• Godot 4.7.0 to 4.7.2 ignore vertex colours on a mesh's first primitive. export_glb warns about affected meshes when the target is godot.

Architecture

Two ways to reach Blender, one set of commands.

flowchart TD    Agent["AI Agent"]    BL["<b>BlenderLens</b><br/>MCP server · JSON-RPC 2.0<br/>Python 3.10+ · no dependencies"]
    Agent <-- "stdio" --> BL
    BL -- "TCP 9877<br/>with its token" --> Window    BL -- "starts and owns" --> Background
    Window["<b>Blender window</b><br/>add-on started<br/><i>you watch, and can undo</i>"]    Background["<b>blender --background</b><br/>no window<br/><i>lives as long as the server</i>"]
    classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;    classDef blender fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;    class Agent,BL svc;    class Window,Background blender;

BLENDERLENS_MODE chooses: auto uses the window when its add-on is started, and a background Blender otherwise. Both run the same command code, on Blender's main thread, where bpy may be used; mesh work goes through bmesh, so it behaves the same with or without a window. Each call that changes the scene is one undo step.

The MCP protocol and the link to Blender are implemented on the standard library, so the package has no runtime dependencies. docs/architecture.md maps the modules, and docs/decisions/ records why each part is built as it is.

Configuration

License

Apache License 2.0 — see LICENSE and NOTICE. BlenderLens is not affiliated with or endorsed by the Blender Foundation.