Skip to main content
Glama
ldraw-mcp

ldraw-mcp

by musharna

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.

PyPI Python License MCP CI Glama DOI

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-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); it is not installed by ldraw-mcp-setup.

Related MCP server: DeepSlate MCP

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


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 tools
bill_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

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      MIT