Developer Tools
BMBrick MCP Server & AI Agent Skill
Generate LEGO-compatible mosaic previews directly from your AI agent. The BMBrick MCP server and Claude Code skill let Claude, Cursor, Codex, and any MCP-compatible client convert a local image into a color-quantized brick mosaic preview without leaving the conversation.
Direct Answer
Install the @bmbrick/agent-mosaic-skill npm package, add the MCP server config to your agent client, then call generate_bmbrick_mosaic with a local image path. The tool returns a watermarked mosaic preview PNG and a link to unlock the full blueprint at bmbrick.com.
Best For
Developers and power users who want to generate mosaic previews as part of an AI-assisted workflow, without opening a browser.
Outputs
Watermarked PNG mosaic preview (up to 64x64 bricks), color-quantized using the real BMBrick palette, plus an unlock URL for full exports.
Avoid
Files over 25 MB, images larger than 25 million pixels, or expectations of unwatermarked output or parts lists from the free tool.
How it works
01 - Install the package
Run npm install -g @bmbrick/agent-mosaic-skill or use npx. The package includes both the MCP server and the mosaic engine.
02 - Configure your agent
Add the BMBrick MCP server to your Claude Code, Cursor, or Codex configuration. The server runs locally and communicates via stdio.
03 - Generate a mosaic
Ask your AI agent to convert a photo to a mosaic. The agent calls generate_bmbrick_mosaic with the image path and returns a preview.
04 - Unlock the full blueprint
The preview includes a watermark. Visit bmbrick.com to unlock PDF instructions, parts lists, and route-specific export files.
Tool parameters
The generate_bmbrick_mosaic tool accepts the following parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| imagePath | string | Yes | — | Absolute path to a local image file (JPEG, PNG, or WebP, under 25 MB) |
| columns | number | No | 48 | Preview width in bricks. Maximum 64. |
| rows | number | No | 48 | Preview height in bricks. Maximum 64. |
| materialMode | string | No | square_1x1 | square_1x1 for 3024 plates or round_1x1 for 98138 tiles. |
| renderMode | string | No | 3D | Render style for the preview image. |
| removeBackground | boolean | No | false | Auto-detect and remove white or transparent backgrounds. |
Installation examples
Claude Code
Add to your ~/.claude/settings.json:
{
"mcpServers": {
"bmbrick": {
"command": "npx",
"args": ["-y", "@bmbrick/agent-mosaic-skill"]
}
}
}Cursor
Add to your .cursor/mcp.json:
{
"mcpServers": {
"bmbrick": {
"command": "npx",
"args": ["-y", "@bmbrick/agent-mosaic-skill"]
}
}
}npm global install
npm install -g @bmbrick/agent-mosaic-skillWhat the tool returns
The MCP tool returns two things:
- Watermarked PNG preview — a color-quantized mosaic rendered with the real BMBrick palette and a visible watermark overlay.
- Unlock URL — a link to bmbrick.com where you can remove the watermark and access PDF instructions, parts lists, PAB CSV, Webrick CSV, and BrickLink XML exports.
Technical limits
| Limit | Value | Notes |
|---|---|---|
| Max input file size | 25 MB | Larger files are rejected before processing |
| Max source pixels | 25,000,000 | Approximately 5000x5000 pixels |
| Max preview grid | 64x64 bricks | Default is 48x48; larger grids need the full web app |
| Palette | Real BMBrick catalog | Same palette used by the web app, including vendor variants |
FAQ
What is the BMBrick MCP server?
The BMBrick MCP server exposes a generate_bmbrick_mosaic tool that any MCP-compatible AI agent can call. It takes a local image path, quantizes it into a LEGO-compatible color palette, and returns a watermarked mosaic preview PNG.
Which AI agents support the BMBrick skill?
Claude Code, Cursor, Codex, and any client that supports the Model Context Protocol (MCP) can use the BMBrick mosaic generation tool.
Is the BMBrick MCP tool free?
The MCP server and Claude Code skill are free and open source under the MIT license. The generated preview includes a watermark; a paid unlock at bmbrick.com removes it and provides full exports.
What image formats are supported?
The tool accepts common image formats including JPEG, PNG, and WebP. The input file must be under 25 MB and the source image must not exceed 25 million pixels.
Can I get parts lists or PDF instructions from the MCP tool?
The free MCP tool returns a watermarked preview only. Full exports (PDF instructions, PAB CSV, Webrick CSV, BrickLink XML, structure BOM) are available after unlocking at bmbrick.com.
Does the tool upload my image to a server?
No. The mosaic engine runs entirely on your local machine. The MCP server processes the image in your local Node.js environment and never transmits the image externally.
Where To Go Next
Next reads: