ldraw-mcp
<div align="center">
# 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.
[](https://pypi.org/project/ldraw-mcp/)
[](https://pypi.org/project/ldraw-mcp/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://github.com/musharna/ldraw-mcp/actions/workflows/ci.yml)
[](https://glama.ai/mcp/servers/musharna/ldraw-mcp)
[](https://doi.org/10.5281/zenodo.21713452)
<img src="docs/hero.png" alt="Two rendered views of a red LEGO car — real studs, transparent glass, rubber tires, steering wheel" width="100%">
<sub>A ~90-line <code>.ldr</code> rendered front-left and rear-right — actual bricks, not a geometric proxy.</sub>
</div>
<!-- mcp-name: io.github.musharna/ldraw-mcp -->
---
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
```bash
# 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-mcp
```
Then 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](#requirements)); it is
> not installed by `ldraw-mcp-setup`.
## Tools
| tool | what it does |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `render_ldraw_file(path, azimuths="-60,120", resolution=640, samples=24)` | Render a model file to a PNG (multi-view, stitched side by side) |
| `render_ldraw_text(ldr, azimuths="-60,120", resolution=640, samples=24)` | Render inline LDraw content without writing a file first |
| `check_renderer()` | Diagnose the Blender / addon / parts-library setup |
| `bill_of_materials(path="", ldr="")` | Part × colour × quantity rows for a model file or inline text |
| `lookup_color(query)` | Colour code ↔ name / RGB / edge / alpha from `LDConfig.ldr` |
| `search_parts(query, limit=50)` | Library parts whose description or file name contains `query` |
`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 point `LDRAW_MCP_BLENDER` at the binary.
Install it yourself (package manager, blender.org, or a local build);
`ldraw-mcp-setup` does not install Blender.
- **ImportLDraw addon** (`io_scene_importldraw`) in Blender's addons dir —
installed by `ldraw-mcp-setup`.
- **LDraw parts library** at `~/.ldraw` (or `LDRAW_LIBRARY_PATH`) —
installed by `ldraw-mcp-setup`.
### Environment variables
| var | meaning |
| -------------------- | --------------------------------------------------------------------------------------- |
| `LDRAW_MCP_BLENDER` | Path to the blender binary (overrides `PATH` lookup) |
| `LDRAW_MCP_DISABLE` | Set to `1` to turn rendering off: `check_renderer` reports unavailable, renders refuse |
| `LDRAW_LIBRARY_PATH` | Path to the LDraw parts library (community convention) |
### Manual setup
If `ldraw-mcp-setup` can't detect things automatically:
- **LDraw library:** download
[complete.zip](https://library.ldraw.org/library/updates/complete.zip)
and unzip so that `~/.ldraw/parts/` exists.
- **ImportLDraw addon:** download the latest release from
[TobyLobster/ImportLDraw](https://github.com/TobyLobster/ImportLDraw/releases)
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_renderer` says NOT FOUND:** run `ldraw-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_importldraw`
in 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](LICENSE).
---
<sub>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.</sub>
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.