Blenderlens MCP Server

BlenderLens

An MCP server that lets an AI agent model, texture and animate in Blender, from a single object to a whole animated scene. You can watch the agent work in your own Blender window and undo anything it does, or let it work in a background Blender with no window. The result is an ordinary .blend file, or an export in the format you need.

What it can do

Once the server is connected, you describe what you want and the agent builds it in Blender. With BlenderLens it can:

• Model: start from primitives, tubes along a path, lathed profiles, 3D text or raw vertices, then extrude, inset, bevel, bisect, solidify and subdivide, or add any Blender modifier.
• Texture: PBR materials with emission and transparency, vertex colours, UV unwrapping, and baked colour, ambient occlusion, normal and lighting textures.
• Animate: key movement, rotation, scale and shape keys into named clips.
• Assemble scenes: place, parent, duplicate and group objects, and drop them until they rest on what is below.
• See its work: render previews from any angle, or a sheet of several views, in shaded, clay or wireframe style.
• Check: measure parts, find ones that pass through each other, and catch broken geometry before you do.
• Deliver: save the .blend, or export glTF, FBX, OBJ, STL, PLY or USD; import existing models; run your own build scripts.

Built for AI agents

An agent can already drive Blender by writing Python, but it works blind: it cannot see the result, guesses at geometry it cannot inspect, and finds out what went wrong only when you open the file. BlenderLens gives it the feedback a person modelling in Blender gets.

Two ways to run

• In your Blender window. Install the BlenderLens add-on and press Start, and the agent works in the Blender you have open. You see each change as it happens, can step in at any point, and can press Ctrl+Z to undo any call.
• In the background. With no add-on, the server starts blender --background itself on the first call that needs it, and keeps it until the server exits. Nothing to set up in Blender.

By default the server uses your window when the add-on is started, and a background Blender otherwise.

Requirements

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 background mode needs.

The Blender add-on

To work in a Blender window, 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 add-on is also attached as a zip to each GitHub release.

How the agent works

The tools are built around one cycle:

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>Save</b><br/>save_file<br/>export_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, edit_mesh shapes it, set_material colours it, animate_object moves 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 the agent looks at. get_object gives exact sizes and counts.
3. Check. check_asset finds broken geometry, unapplied scale, a misplaced origin, UV and texture problems, and parts passing through each other. measure_objects says what touches what.
4. Save. save_file keeps the .blend; export_file and export_glb write other formats and read the file back.

Tools

Units are metres, rotations degrees, and Z is up. Face indices are the ones get_mesh lists, and change after any edit that adds or removes faces.

Session

Inspecting

Building

Arranging

Checking and seeing

Files

Python and undo

Exporting glTF

export_glb writes a .glb, then opens the written file and reports what it actually holds: the node tree, triangle counts, materials, and estimates of draw calls and texture memory. It warns about what went missing on the way, such as objects that are not in the file, a metaball written with no mesh, shape keys dropped by applied modifiers, textures without the UVs they need, and normal maps without tangents.

Its target says which engine will load the file, and so which warnings come back: godot, threejs, or generic (the default), which gives both:

• Godot: names it reads as import hints (Rock_col gets a collision body), animations it will loop because of their names, nodes it will rename, extensions it cannot load, and vertex colours that Godot 4.7.0 to 4.7.2 ignore on a mesh's first primitive. Draco compression is refused, since Godot cannot import it.
• three.js: extensions GLTFLoader cannot load, or loads only with a decoder the app must set up. Collision proxies made by create_collision are left out, since three.js would draw them.

Project rules

When a set of models must follow the same conventions, check_asset can hold each one to a triangle budget and to your own rules, given inline or as a rules_file. The rules are a JSON object, and 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.

The same checks run without an agent, for example in a build pipeline. A .glb is read with no Blender; a .blend is opened in a background Blender. --target adds that engine's warnings, and --json prints the full result. The command exits 0 when the model passes, 1 when it fails, and 2 when it could not be checked.

blenderlens-mcp check lantern.glb --budget 2000 --rules rules.json

Errors

When a tool refuses a call, it changes nothing and returns error (what went wrong), exit (a fixed number for each kind), kind and hint (what to do about it).

Limitations

• 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.
• 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.
• Blender's glTF exporter writes a metaball as an empty node. check_asset reports metaballs as errors, and export_glb warns about them.

Architecture

flowchart TD
    Agent["AI Agent"]
    BL["<b>BlenderLens</b><br/>MCP server<br/>Python 3.10+<br/>no dependencies"]

    Agent <-- "stdio, JSON-RPC 2.0" --> 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;

Both ways run the same command code, on Blender's main thread; 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 built on the Python 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.