ldraw-mcp

io.github.musharnaPublished by GitHub account musharnav0.3.1Updated Oct 24, 2026

Render LDraw/LEGO models to images with real part geometry via headless Blender + ImportLDraw

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & Design

Overview

AI-generated overview

Renders LDraw/LEGO model files to PNG images with real part geometry using headless Blender, and answers part, colour and bill-of-materials queries.

What you can do
The server renders LDraw files (.ldr, .mpd, .dat) or inline LDraw text to PNG images through headless Blender and the ImportLDraw addon, producing multi-view renders stitched side by side at configurable azimuths, resolution and sample count. It also offers read-only query tools: bill_of_materials for part, colour and quantity rows, lookup_color for colour code, name, RGB, edge and alpha data, and search_parts for library parts matching a query. check_renderer diagnoses the Blender, addon and parts-library setup.
When to use it
Use it when an assistant needs to see an actual LEGO build rather than a geometric proxy, for example to spot crossed rotation matrices, floating plates or sunken windows in an exported model. It also suits quick part, colour and bill-of-materials lookups on LDraw files.
Requirements
Runs locally as a Python package (pypi ldraw-mcp, run with uvx). Needs Blender 4.x on PATH or LDRAW_MCP_BLENDER set to the binary, the ImportLDraw addon, and an LDraw parts library at ~/.ldraw or LDRAW_LIBRARY_PATH; ldraw-mcp-setup installs the addon and library but not Blender. Rendering uses Cycles on CPU, so no GPU or display is needed. The three query tools need no Blender.
Before you install
Rendering runs Blender as a local process and reads model files and the parts library from disk; the query tools are read-only. No authentication, API keys or network access are declared. Setup downloads the LDraw parts library and the ImportLDraw addon from third parties.

Installation

In SourceWeft

  1. Open ldraw-mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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]

[Two rendered views of a red LEGO car — real studs, transparent glass, rubber tires, steering wheel]

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

bash
# 1. installpip install ldraw-mcp
# 2. install the LDraw parts library + ImportLDraw addonldraw-mcp-setup
# 3. register with Claude Codeclaude 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.

Tools

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

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

varmeaning
LDRAW_MCP_BLENDERPath to the blender binary (overrides PATH lookup)
LDRAW_MCP_DISABLESet to 1 to force is_available() to False
LDRAW_LIBRARY_PATHPath 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.

Source: README.md at commit 1f9b386

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v0.3.1LatestSep 23, 2026
  2. v0.3.0Sep 19, 2026
  3. v0.2.3Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts