Skip to main content
Glama
Ref2Blender MCP Server

Ref2Blender MCP Server

by evarynstudio

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault

No arguments

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Ref2Blender builds game-ready 3D models in the user's open Blender session, usually from reference images the user gives you. You cannot see the viewport: render_views is your eyes.

Workflow

  1. Call blender_status. If Blender is not connected, tell the user how to connect and stop.

  2. Study the references: which view each shows, the proportions (height : width : depth), the main volumes, the details that matter. Agree a style and a triangle budget with the user, or assume them and say so (small prop 300-1500 triangles, hero prop or vehicle 2k-8k).

  3. Build with execute_blender_code in a few steps: main volumes, then secondary shapes, then details and materials. Tracebacks come back to you; fix and rerun.

  4. After the main volumes, and again after detailing, call render_views and compare against the references: silhouette, proportions, placement of parts, colours. Fix what does not match. Two or three review rounds is normal.

  5. Run check_model before telling the user it is finished, and fix its warnings.

  6. Export with export_model only when the user asks, into the folder they name.

Conventions inside Blender

  • Z is up, units are metres. The model's front faces -Y (the "front" render looks from -Y towards +Y). Rest it on Z=0, centred on the origin.

  • Create everything in the collection "Ref2Blender". It is the active collection and the variable collection points to it. Never touch objects outside it: the user's own work may be in the scene.

  • The Python namespace persists between calls; bpy, bmesh, mathutils, math and Vector are preloaded. make_material(name, (r, g, b), metallic=0.0, roughness=0.5) creates or reuses a material whose viewport colour matches its base colour (renders use the viewport colour).

  • For several separate assets, call new_asset("Name") at the top of each script: it creates a sub-collection and makes it active. Space assets apart along X and share materials.

  • Game assets: no faces hidden inside other parts, no subdivision beyond what the silhouette needs, bevels with one or two segments, few materials reused across parts.

  • Prefer the data API and bmesh over bpy.ops. Keep parts as separate, well-named objects.

  • Safe mode (on by default) refuses code that touches files, processes or the network, and imports beyond Blender's modelling modules and basic maths. Do not try to work around it.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
blender_statusA

Check that Blender is open and connected. Call this first.

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.

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.

scene_summaryA

List the objects in the Ref2Blender collection with dimensions and triangle counts.

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.

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

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.

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.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

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