ldraw-mcp
ldraw-mcp lets MCP clients render and inspect LDraw LEGO models via Blender, plus query LDraw library metadata.
Render
.ldr/.mpd/.datfiles or inline LDraw text to stitched multi-azimuth PNGs with configurable resolution and samples.Diagnose whether the Blender, ImportLDraw addon, and LDraw parts-library stack is available and why not.
Generate bills of materials from model files or inline text, expanding MPD submodels and flagging unknown colors or missing parts.
Look up LDraw colors by code or name, returning RGB, edge color, alpha, and finish.
Search the LDraw parts library by description or filename substring.
Query tools are read-only; color/part lookups need the LDraw library, while rendering needs the full Blender setup.
Renders LDraw models (.ldr/.mpd/.dat) to images using headless Blender with real part geometry, enabling visual inspection of LEGO builds.
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., "@ldraw-mcp render output/build.ldr and tell me what looks wrong"
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.
ldraw-mcp
Give your MCP client eyes for LEGO® models.
Render LDraw files (.ldr / .mpd / .dat) to images with real part
geometry — studs, slopes, window glass — using headless Blender and the
ImportLDraw addon. The output looks like a BrickLink Stud.io render, with no
GUI anywhere in the loop.
A ~90-line .ldr rendered front-left and rear-right — actual bricks, not a geometric proxy.
Point a vision-capable model at a build and it sees the actual bricks: crossed rotation matrices, floating plates, sunken windows — the kinds of export bugs a geometric proxy render will happily hide.
Quickstart
# 1. install
pip install ldraw-mcp
# 2. install the LDraw parts library + ImportLDraw addon
ldraw-mcp-setup
# 3. register with Claude Code
claude mcp add ldraw -- ldraw-mcpThen ask things like "render output/build.ldr and tell me what looks wrong" — the model sees the render, not just the text.
Blender is a prerequisite (see Requirements); it is not installed by
ldraw-mcp-setup.
Related MCP server: DeepSlate MCP
Tools
tool | what it does |
| Render a model file to a PNG (multi-view, stitched side by side) |
| Render inline LDraw content without writing a file first |
| Diagnose the Blender / addon / parts-library setup |
| Part × colour × quantity rows for a model file or inline text |
| Colour code ↔ name / RGB / edge / alpha from |
| Library parts whose description or file name contains |
azimuths is a comma-separated list of view angles in degrees; each is
rendered and the views are stitched horizontally. Elevation is fixed at
22°. Higher samples = cleaner but slower.
A part the LDraw library does not have cannot be drawn. The render tools still return the picture of the rest, followed by a text block that names each file the importer could not find. When every file is found, the image comes alone.
The render tools and bill_of_materials follow the same references. Files
next to the model (sub.ldr, models/wheel.ldr) and library parts are
followed. A reference that could leave the folder it is looked up in (..,
an absolute path, a drive, ~), or a file in the model's folder that links
outside it, is refused with the same message by every tool. Inline text
follows the same rule.
The three query tools are read-only and need no Blender. bill_of_materials
expands MPD sub-models (and sibling .ldr/.mpd files next to the model) with
their multiplicity, and resolves colour 16 to the colour of the referencing
line; colour 24 (edge) is reported as 24. It counts without a parts library —
descriptions and colour names are then null. A colour code LDConfig.ldr
does not define is listed under unknown_color_codes, a part the library lacks
under parts_not_in_library; neither is dropped. A sub-model reference cycle is
an error that names the cycle. lookup_color and search_parts need the
library (ldraw-mcp-setup).
Requirements
Blender 4.x on
PATH, or pointLDRAW_MCP_BLENDERat the binary. Install it yourself (package manager, blender.org, or a local build);ldraw-mcp-setupdoes not install Blender.ImportLDraw addon (
io_scene_importldraw) in Blender's addons dir — installed byldraw-mcp-setup.LDraw parts library at
~/.ldraw(orLDRAW_LIBRARY_PATH) — installed byldraw-mcp-setup.
Environment variables
var | meaning |
| Path to the blender binary (overrides |
| Set to |
| Path to the LDraw parts library (community convention) |
Manual setup
If ldraw-mcp-setup can't detect things automatically:
LDraw library: download complete.zip and unzip so that
~/.ldraw/parts/exists.ImportLDraw addon: download the latest release from TobyLobster/ImportLDraw and install it via Blender > Preferences > Add-ons > Install, or unzip into
~/.config/blender/<version>/scripts/addons/io_scene_importldraw/. (Launch Blender once first so the config directory exists.)
Troubleshooting
check_renderersays NOT FOUND: runldraw-mcp-setup, or set the relevant env var above.No GPU / WSL2 / containers: rendering uses Cycles on CPU, which works headless everywhere — no GPU or display needed. A ~150-part model takes a few seconds at the default 640px / 24 samples.
"no mesh objects imported": the addon couldn't resolve parts — usually a wrong or incomplete LDraw library path. Re-run setup or check
LDRAW_LIBRARY_PATH.Addon not enabled: the render script enables it automatically per run; if a manual Blender session complains, enable
io_scene_importldrawin Preferences > Add-ons.
Provenance
This renderer was extracted from the prompt2brick project, where it started life as the vision critic's "see the actual model" path. prompt2brick keeps its own vendored copy of the render wrapper and Blender script, but this repo is the canonical source going forward — fixes and improvements to the renderer should land here first and be ported back into prompt2brick.
License
MIT — see LICENSE.
LEGO® is a trademark of the LEGO Group, which does not sponsor, authorize, or endorse this project. This tool is not affiliated with the LEGO Group, BrickLink, or the LDraw.org organization.
Available Tools
6 toolsbill_of_materialsA
Bill of materials for an LDraw model: part x colour x quantity rows.
Give path (a .ldr/.mpd file) or ldr (inline LDraw text), not both. MPD
sub-models are expanded with their multiplicity, and colour 16 inherits the
colour of the line that referenced the sub-model. Part descriptions and
colour names come from the LDraw library when one is installed; without it
the counts are the same and those fields are null. A colour code that
LDConfig.ldr does not define is listed in unknown_color_codes, and a part
the library lacks in parts_not_in_library.
Inputs: ldr, path. Returns: object
check_rendererA
Report whether the LDraw rendering stack is available and why not.
Inputs: no named parameters. Returns: result
lookup_colorA
Look up LDraw colours in the library's LDConfig.ldr.
query is a colour code (4, or a direct colour 0x2FF8800) or part of a
name (dark blue, Trans_Red). Returns code, name, RGB, edge colour, alpha
and finish for each match; an unknown code returns no matches.
Inputs: query (required). Returns: object
render_ldraw_fileA
Render an LDraw model file (.ldr/.mpd/.dat) to a PNG image.
Views are rendered at each comma-separated azimuth (degrees) and stitched side by side. Higher samples = cleaner but slower. Bounds: resolution 32..2048 px per view, samples 1..1024, 1..8 azimuths, and resolution^2 x samples x views at most 2**27. A referenced file the LDraw library lacks is left out of the picture and named in a text block after the image.
Inputs: path (required), samples, azimuths, resolution.
render_ldraw_textA
Render inline LDraw content (the text of a .ldr file) to a PNG.
Useful for quick experiments without writing a file first. Same bounds as render_ldraw_file.
Inputs: ldr (required), samples, azimuths, resolution.
search_partsA
Search the LDraw library's parts by description or file-name substring.
Case-insensitive, runs of spaces collapsed (brick 2 x 4 matches the
header Brick 2 x 4). Returns at most limit parts (max 200) plus the
total number of matches.
Inputs: query (required), limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool occupies a clearly distinct niche: rendering (file vs inline text), BOM analysis, colour lookup, part search, and environment diagnostics. The closest pair, render_ldraw_file and render_ldraw_text, is cleanly separated by input form (path vs inline LDraw text) in both name and description. No tool overlaps another's job.
Five of six names follow a consistent snake_case verb_noun pattern (check_renderer, lookup_color, render_ldraw_text, render_ldraw_file, search_parts). bill_of_materials deviates as a bare noun phrase, though it is still immediately readable and unambiguous.
Six tools is well within the sweet spot and each one earns its place: two render entry points, two query tools (parts, colours), one analysis tool, and one diagnostic. Nothing feels padded or redundant for a focused LDraw rendering/inspection server.
The read-only lifecycle is well covered: render a model or raw text, extract a bill of materials, search parts, look up colours, and verify the rendering stack. Minor gaps remain — no model validation/parse-error reporting tool and no way to list library categories or discover models — but agents can work around these.
Maintenance
Related MCP Connectors
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Blender and GLB/FBX/USD/STL rendered on cloud GPUs for AI agents: product shots, turntables, MP4
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Create, edit, render, save, and export voxel models with interactive 3D previews.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants like Codex or ChatGPT to inspect and control a local Blender scene, including creating objects, editing materials, setting cameras and lights, rendering previews, and saving safe copies of .blend files.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that renders Minecraft structure files (NBT / Sponge schematic / Litematic) into PNG preview images using vanilla Minecraft resources.1MIT
- AlicenseBqualityCmaintenanceAn MCP server that builds and modifies Blender .blend files, supporting both headless generation and live interaction with an open Blender window.16MIT
- AlicenseNot gradedqualityDmaintenanceEnables any MCP client to drive Blender 5.2 LTS through natural language, with tools for scene inspection, object creation and transformation, material and modifier handling, rendering, viewport capture, and guarded Python execution.2MIT