brick-mcp

Personal 0.3 edition based on datakurre/brick-mcp, with the upstream Git history preserved. This is an independent extension, not an official BrickLink Studio integration.

Our additions include atomic construction steps with rollback, subassemblies and illustrated instructions, geometry-based part dimensions, and a native Windows bridge that runs Studio Stability and Connectivity checks on each committed step without Computer Use. See LOCAL_SETUP.md for setup and native_bridge/README.md for the native worker.

The native worker requires a separately installed Studio. Runtime binaries, local caches, generated models and rendered media are excluded from this repository. Fabric sails without physics data remain explicitly unverified; see UPGRADE_RESULT.md for verification history and limitations.

The repository also preserves the cottage, pirate ship and Orc Kraken build scripts. make_orc_presentation.py, presentation_blender.py and finish_orc_presentation.py export the ship geometry, render stills/assembly stages and package the videos. These are workstation-specific examples: review their local paths and provide the generated model, Blender and FFmpeg before running them.

Verification of this snapshot: 235 tests passed (python -m pytest tests/ -q, 2026-09-06). Native engine integration checks are separate from this unit suite.

An MCP server that lets AI assistants create, inspect, and edit LEGO models stored in BrickLink Studio (.io) and LDraw (.ldr) files. Ask your AI assistant to open a file, move parts around, change colors, add new bricks — then save back to a file that opens directly in BrickLink Studio.

Features

• Open and save BrickLink Studio .io files and plain LDraw .ldr / .mpd files

• List parts, inspect the bill of materials, and view building-instruction steps

• Add, remove, move, rotate, and recolor individual parts by session ID

• Search the built-in parts database and look up LDraw color codes

• Create new models from scratch with new_model()

Related MCP server: IFCX MCP

Instruction workflow (0.2)

Use apply_step for a named construction step with validation, rollback and two PNG previews. edit_step inserts/renames/reorders/splits steps and moves parts. create_submodel builds independent assemblies; undo_last_edit restores memory. validate_build checks ordinary stud connections and vertical insertion access. render_step highlights new parts. export_instructions writes native Studio IO, MPD, an illustrated HTML booklet and a JSON step/BOM manifest.

Aliases resolve to canonical parts and dimensions come from actual LDraw geometry. Complex connectors remain unverified. batch defaults to atomic memory edits; save separately. atomic=False enables explicit legacy best-effort execution.

Requirements

• Python ≥ 3.14

• Nix (recommended — handles all dependencies automatically)

Without Nix, install Python dependencies manually:

pip install "fastmcp>=3.1.0" "pyzipper>=0.3.6" "numpy>=2.4,<3" "pillow>=12,<13"

MCP client configuration

VS Code

The repository ships a ready-to-use .vscode/mcp.json using Nix:

{
  "servers": {
    "bricks": {
      "type": "stdio",
      "command": "nix",
      "args": ["run", "/path/to/brick-mcp"]
    }
  }
}

Replace /path/to/brick-mcp with the path to your local clone, or use github:datakurre/brick-mcp to run directly from GitHub without cloning.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "bricks": {
      "command": "nix",
      "args": ["run", "github:datakurre/brick-mcp"]
    }
  }
}

Without Nix (local Python)

{
  "mcpServers": {
    "bricks": {
      "command": "python",
      "args": ["/path/to/brick-mcp/main.py"]
    }
  }
}

Typical workflow

1. open_model("path/to/model.io")   — load a file
2. list_parts()                      — see what's inside
3. change_color("abc123", 4)         — change a part to Red
4. add_part("3001.dat", 4, x=0, y=-24, z=0)  — place a new 2×4 brick
5. save_model()                      — write back to the original file

Tool reference

File operations

Inspection

Editing

Parts & colors database

Coordinate system

LDraw uses LDU (LDraw Units). Key measurements:

The Y-axis is inverted: y=0 is the build plate, y=-24 is one brick above it. X and Z are the horizontal plane.

Common LDraw color codes

Use list_colors() for the full list.

Common part numbers

Use search_parts("brick 2x4") to find part numbers you don't know.