Ref2Blender MCP Server
Runs AI-generated Blender Python inside a live Blender session via an add-on bridge: executes code, returns scene summaries with object dimensions and triangle counts, renders orthographic and perspective check views of the generated model, and clears the dedicated Ref2Blender collection.
Exports the generated asset as an FBX prepared for Unity (scale 1, rotation 0, front towards +Z, pivot at bottom centre, LODGroup from _LOD0/_LOD1 names, convex collider child, palette material and swatch texture), with an optional editor postprocessor script for collider and unfiltered palette import.
Exports the generated asset as an FBX prepared for Unreal Engine (front towards +X, LODs in an FBX LodGroup, collision mesh named UCX__00).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ref2Blender MCP Server Model this chair from the two images. Low poly, under 800 triangles."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ref2Blender
Give your AI assistant reference images and get a game-ready 3D model built in your own Blender scene, then exported for Unity, Unreal Engine or Godot.
Ref2Blender is a Blender add-on plus an MCP server. The assistant (Claude Code, Claude Desktop, Cursor, or any MCP client) writes Blender Python, renders the result from fixed views, compares it against your references and corrects it. When you are happy, it exports the asset with the pivot, scale, LODs, collision and materials a game engine expects.
It is focused on one job, game assets from references. For a general-purpose Blender integration with asset libraries and AI mesh generation, see blender-mcp.
What it does
Model from references. Explicit geometry (vertices, primitives, modifiers), so the result is editable, not a dense scanned mesh.
Check renders. Orthographic front/back/left/right/top/bottom and two perspective views, auto-framed, showing only the generated model.
Triangle budgets. A game-readiness report: triangles against a budget, materials, missing UVs, n-gons, warnings.
Engine export that leaves your scene untouched:
modifiers applied, parts joined, pivot at the bottom centre, UVs unwrapped where missing;
LODs, each level with half the triangles;
a convex collision mesh named the way each engine expects;
a palette: every colour collapsed into one material and one small swatch texture.
Asset sets. Several assets in one scene, sharing materials, exported one file each.
Safe mode, on by default: generated code that touches files, processes or the network is refused before it runs.
No telemetry. The local connection is bound to
127.0.0.1and protected by a random token created each time you press Connect.
Related MCP server: game-asset-mcp
Requirements
Blender 4.2 or newer.
Python 3.10 or newer for the MCP server (it runs outside Blender).
An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, and so on.
Install
1. Install the server and the add-on
pip install git+https://github.com/evarynstudio/ref2blenderref2blender-mcp install-addonThe second command copies the add-on into the add-ons folder of every Blender 4.2+ it finds. Then, in Blender: Edit > Preferences > Add-ons, enable Ref2Blender.
Prefer not to use the command? Download ref2blender-<version>.zip from the Releases page
and install it in Blender with Edit > Preferences > Get Extensions > Install from Disk.
2. Add the server to your MCP client
Claude Code:
claude mcp add ref2blender -- ref2blender-mcpClaude Desktop, Cursor and other clients that use a JSON config:
{
"mcpServers": {
"ref2blender": { "command": "ref2blender-mcp" }
}
}With uv you can skip the pip install and use
"command": "uvx", "args": ["--from", "git+https://github.com/evarynstudio/ref2blender", "ref2blender-mcp"].
Use
In Blender, press
Nin the 3D viewport, open the Ref2Blender tab and press Connect.Give your assistant the reference images and say what you want, for example:
Model this chair from the two images. Low poly, under 800 triangles.
Ask for changes in plain words. When it looks right:
Export it to
D:/MyGame/Assets/Models/Chairfor Unity, with collision and a palette.
Everything the assistant creates goes into a collection called Ref2Blender; the rest of your
scene is left alone.
Tools the server exposes
Tool | What it does |
| Checks that Blender is open and connected |
| Runs Python in Blender; returns output, errors and a scene summary |
| Returns check renders of the model as images |
| Lists objects with dimensions and triangle counts |
| Game-readiness report, optionally against a triangle budget |
| Exports for |
| One file per asset sub-collection |
| Empties the |
Engine notes
Engine | Format | Result |
Unity | FBX | Scale 1, rotation 0, front towards +Z. LODGroup built from the |
Unreal Engine | FBX | Front towards +X. LODs in an FBX LodGroup, collision as |
Godot | GLB | Collision as |
Unity: copy unity/Ref2BlenderPostprocessor.cs into
Assets/Editor/ once per project. It turns the _Collider child into a convex MeshCollider
and imports palette textures unfiltered. LODs work without it.
Verification status. The Unity preset is checked inside Unity 6 (scale, rotation, pivot, orientation, LODGroup, collider, palette). The Unreal and Godot presets follow each engine's documented conventions and round-trip correctly through Blender, but have not yet been checked inside those engines. Reports are welcome.
Without an MCP client
The add-on also has a built-in mode that calls the Claude API directly from the panel with
your own Anthropic API key (With an API key section). It installs the anthropic package
into a private folder the first time you use it.
There is also a small command-line client, r2b.py, that needs only the Python
standard library: python r2b.py ping, exec, render, check, export.
Security
Ref2Blender runs code written by an AI model inside your Blender. Read this before using it.
Safe mode is a guard rail, not a sandbox. It inspects the code before running it and restricts the Python builtins, refusing file, process and network access and any import beyond Blender's modelling modules and basic maths. Python cannot be fully sandboxed inside its own process, so a determined bypass is possible. It protects against a model wandering outside "build geometry", not against a deliberately hostile one.
Save your work first. Generated code can still delete or change objects in the scene.
Exports write files where the assistant is told to. Review the path it proposes.
You can turn safe mode off in the add-on preferences if a task needs it (loading an image texture, for example). The panel shows a warning while it is off.
The bridge listens only on
127.0.0.1and requires a per-session token stored in~/.ref2blender/bridge.json. Other programs running as your user could read that file.
Development
pip install -e .Tests run in a headless Blender (replace blender with the path to your executable):
blender --background --factory-startup --python tests/smoke_test.pyblender --background --factory-startup --python tests/export_test.pyblender --background --factory-startup --python tests/safe_test.pypython tests/mcp_test.py "path/to/blender"Build the installable extension zip into dist/ (create the folder first):
blender --command extension build --source-dir ref2blender --output-dir distThe interface is in English with a Catalan translation; other languages can be added in
ref2blender/i18n.py.
Licence
GPL-3.0-or-later, the same licence as Blender. See LICENSE.
Available Tools
8 toolsblender_statusA
Check that Blender is open and connected. Call this first.
Inputs: no named parameters. Returns: result
check_modelB
Game-readiness report: triangles (against the budget, if given), materials, missing UVs, n-gons, and warnings to fix before the model is finished.
Inputs: asset, triangle_budget. Returns: result
clear_modelA
Delete everything in the Ref2Blender collection and reset the Python namespace. Destructive: use it only to start a new model, when the user agrees to drop the current one.
Inputs: no named parameters. Returns: result
execute_blender_codeB
Run Python code in the user's Blender session (main thread, Object Mode).
Returns what the code printed, the traceback if it raised, and a summary of the objects in the Ref2Blender collection with dimensions and triangle counts. The namespace persists between calls.
Inputs: code (required). Returns: result
export_all_assetsB
Export every asset sub-collection to its own file in folder, each pivoted on its
own base. Same options and same caution as export_model.
Inputs: folder (required), lods, pivot, engine, +2 more. Returns: result
export_modelA
Export the model for a game engine. Writes a file on the user's disk: only call it when the user asked for an export, with an absolute path they chose.
The scene is not modified (the export works on copies): modifiers are applied, parts
without UVs are unwrapped, everything is joined into one mesh named after the file
(separate keeps the parts), and the pivot goes to the bottom centre. The extension is
set by the engine: FBX for unity and unreal, GLB for godot and generic.
lods: extra detail levels, each with half the triangles (0-4). collision: add a convex collision mesh named the way the engine expects. palette: replace all materials with one material and a small colour-swatch PNG written next to the model (colour only).
Inputs: path (required), lods, asset, pivot, +4 more. Returns: result
render_viewsA
Render the model, auto-framed, and return one image per view.
front/back/left/right/top/bottom are orthographic (front = camera on -Y looking
towards +Y; right = camera on +X). three_quarter is a perspective view from the
front-right and above; three_quarter_back from the back-left and above. Only the
Ref2Blender collection is shown. Pass asset to render a single asset sub-collection.
Inputs: views (required), size, asset.
scene_summaryA
List the objects in the Ref2Blender collection with dimensions and triangle counts.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a distinct role: status check, code execution, validation, summary, rendering, clearing, and two export variants. The only mild overlap is between check_model and scene_summary (both report triangle counts/dimensions), and execute_blender_code also returns an object summary, but the descriptions frame these as validation vs. listing vs. escape hatch.
Seven of eight names follow a predictable snake_case verb_noun pattern (check_model, export_model, clear_model, render_views, execute_blender_code). The exceptions are blender_status and scene_summary, which are noun-first, but they remain readable and unambiguous.
Eight tools is well within the sweet spot for a Blender bridge server. Each tool earns its place: status, execution, validation, summary, render, clear, and two export scopes.
The lifecycle is covered end to end: connect (blender_status), build/modify (execute_blender_code), inspect (scene_summary, check_model), visualize (render_views), export (export_model, export_all_assets), and reset (clear_model). The code-execution tool serves as a general escape hatch for any missing operations.
Maintenance
Related MCP Connectors
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
3D avatar/asset foundry: text/image -> rigged, validated, engine-ready GLB via x402.
Turn text or an image into an animation-ready 3D model (GLB): generate, rig, animate, retexture.
Turn prompts into production-ready game assets: animated characters, textures, terrain, VFX, HUD.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered 3D content creation in Blender through natural language, including text-to-3D, image-to-3D, animation, rigging, rendering, and export.3MIT
- AlicenseAqualityBmaintenanceEnables AI agents to generate game-ready 3D assets from reference images with PBR textures, and to retexture meshes the user already owns, while recording full provenance for every generated file.2013MIT
- AlicenseCqualityBmaintenanceEnables AI agents to build game assets in Blender by modeling, lighting, rendering previews to inspect and correct, validating against engine budgets, and exporting to GLB/FBX.126MIT
- AlicenseBqualityCmaintenanceEnables LLMs such as Claude to drive Blender through high-level tools for real-world-scale modeling, PBR texturing, lighting, rendering, rigging/animation, and UE5 game-asset baking and export. It also provides asset-library search, reference comparison, quality inspection, and import/export of common 3D file formats.58MIT