Skip to main content
Glama
Ref2Blender MCP Server

Ref2Blender MCP Server

by evarynstudio

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.1 and 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/ref2blender
ref2blender-mcp install-addon

The 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-mcp

Claude 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

  1. In Blender, press N in the 3D viewport, open the Ref2Blender tab and press Connect.

  2. 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.

  3. Ask for changes in plain words. When it looks right:

    Export it to D:/MyGame/Assets/Models/Chair for 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

blender_status

Checks that Blender is open and connected

execute_blender_code

Runs Python in Blender; returns output, errors and a scene summary

render_views

Returns check renders of the model as images

scene_summary

Lists objects with dimensions and triangle counts

check_model

Game-readiness report, optionally against a triangle budget

export_model

Exports for unity, unreal, godot or generic (GLB)

export_all_assets

One file per asset sub-collection

clear_model

Empties the Ref2Blender collection

Engine notes

Engine

Format

Result

Unity

FBX

Scale 1, rotation 0, front towards +Z. LODGroup built from the _LOD0, _LOD1... names

Unreal Engine

FBX

Front towards +X. LODs in an FBX LodGroup, collision as UCX_<Name>_00

Godot

GLB

Collision as <Name>-convcolonly

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.1 and 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.py
blender --background --factory-startup --python tests/export_test.py
blender --background --factory-startup --python tests/safe_test.py
python 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 dist

The 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 tools
blender_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      58
      MIT