Ref2Blender MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
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
Call blender_status. If Blender is not connected, tell the user how to connect and stop.
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).
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.
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.
Run check_model before telling the user it is finished, and fix its warnings.
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
collectionpoints 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
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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 |
| 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
( 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 |
| 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
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.