Brickognize MCP Server
Brickognize MCP server lets you check the Brickognize API and identify LEGO items from local images.
Check if the Brickognize image recognition API is online and responsive.
Identify any LEGO item (part, set, minifigure, or sticker) from a JPEG, PNG, or WebP image.
Identify a specific LEGO part from a photo when you know the image shows a single piece.
Identify a LEGO set from a photo of its box, assembled model, or instructions.
Identify a LEGO minifigure from a photo.
Optionally include raw Brickognize API responses for debugging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Brickognize MCP Server Identify the LEGO set in /Users/me/Desktop/lego_box.jpg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Brickscope
Identify LEGO parts, sets, and minifigures from images — as a CLI tool or an MCP server for AI assistants.
Powered by the Brickognize API and Rebrickable.
Huge thanks to Piotr Rybak for creating the Brickognize service and making LEGO recognition accessible to everyone!
CLI
npm install -g brickscope
brickscope identify photo.jpg --type part
brickscope scan pile.jpg --detect-only # several parts in one photo
brickscope part 3001 --color Black
brickscope set 75192
brickscope minifig fig-012805Or run without installing: npx brickscope identify photo.jpg
Related MCP server: openai-vision-mcp-server
MCP Server
For AI assistants (Claude, Cursor, etc.), add to your MCP config:
{
"mcpServers": {
"brickscope": {
"command": "npx",
"args": ["-y", "brickscope", "mcp"],
"env": {
"REBRICKABLE_API_KEY": "your-key-here",
"BRICKOGNIZE_CACHE": "sqlite"
}
}
}
}HEIC decoding runs in a disposable worker with cancellation and a 30-second timeout; images over 100 megapixels are rejected before RGBA decoding. Decoder diagnostics go to stderr, keeping JSON output clean. Uploads are resized to at most 2048 pixels on the long side. File contents determine the decoder: JPEG/PNG/WebP magic overrides the extension, HEIF brands use libheif, and AVIF uses sharp (converted to JPEG for upload). Embedded HEIC ICC profiles, including Display-P3, are not applied by this decoder; colors may shift. Export an sRGB JPEG when accurate color matters.
Scan previews echo padding, isolateParts and detectionSettings; the CLI saves and restores them in regions.json. MCP callers must pass them back with approved boxes. Part lookups can return partial set lists; keep the fetched results and follow remainingColors.
Configuration
Config file (CLI)
brickscope config initCreates ~/.config/brickscope/config.json with your Rebrickable API key and cache settings.
Environment variables
Variable | Default | Description |
| — | Free API key from rebrickable.com/api. Required for lookup tools. |
|
| Cache mode: |
Environment variables take priority over the config file.
Features
Image recognition — identify parts, sets, minifigures, and stickers from photos
Batch processing — identify multiple images in parallel
Multi-part scan — find, crop and identify several parts in one photo, with previews an AI assistant can review and correct
Part lookup — colors, set appearances via Rebrickable
Set inventory — full parts list, year, theme, piece count
Minifigure lookup — details and set appearances
Caching — in-memory or SQLite cache for Rebrickable API responses
Config file — save API key and preferences once, use everywhere
Photo tips for scanning several parts
Put the parts on a plain, matte surface (no wood grain or patterned fabric), with even light from above and a small gap between parts. Use the original photo from the phone — messengers shrink it so much that small parts like pins lose their detail. The surface color matters too: fuchsia or mint-green paper keeps ~99% of LEGO parts clearly visible, while white paper hides white, transparent and light gray parts. brickscope scan also returns tips for the photo you just took. More
Examples
See the examples folder for prompt templates.
Development
pnpm install
pnpm build
pnpm dev # Watch mode
pnpm test # Unit + integration tests
pnpm lint # ESLint
pnpm format # PrettierRequires Node.js 22.12+ and pnpm 12. The build uses TypeScript 7 (@typescript/native), while the typescript package is aliased to the TypeScript 6 API (@typescript/typescript6) because typescript-eslint and editors still need it.
Releasing
Releases are automated with release-please. PR titles follow Conventional Commits and are squash-merged: fix: bumps the patch version, feat: the minor version. After each merge to main, release-please keeps a release PR up to date with the version bump and CHANGELOG.md. Merging it tags the release, creates a GitHub Release and publishes to npm.
License
MIT. HEIC photos are decoded with libheif-js (LGPL-3.0), used unmodified as a separate npm dependency. sharp also uses libvips (LGPL-3.0).
Available Tools
5 toolsbrickognize_healthBrickognize Health CheckARead-onlyIdempotent
Check whether the Brickognize image recognition API is online and responsive. Call this before recognition if you suspect the service might be down. Takes no parameters.
Inputs: no named parameters.
brickognize_identifyIdentify LEGO ItemARead-onlyIdempotent
Identify any LEGO item (part, set, minifigure, or sticker) from a photograph. Use this when the item type is unknown or the image may contain multiple types.
Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP). Returns top matches with confidence scores, IDs, names, categories, and links to BrickLink/BrickOwl.
Inputs: imagePath, includeRaw.
brickognize_identify_figIdentify LEGO MinifigureARead-onlyIdempotent
Identify a LEGO minifigure from a photograph. Use instead of brickognize_identify when you know the image shows a minifigure.
Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP). Returns matched minifigures with IDs, names, confidence scores, and links.
Inputs: imagePath, includeRaw.
brickognize_identify_partIdentify LEGO PartARead-onlyIdempotent
Identify a specific LEGO part/brick/element from a photograph. Use instead of brickognize_identify when you know the image shows a single LEGO piece for more accurate results.
Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP). Returns matched parts with IDs, names, confidence scores, and links.
Inputs: imagePath, includeRaw.
brickognize_identify_setIdentify LEGO SetARead-onlyIdempotent
Identify a LEGO set from a photograph of its box, assembled model, or instructions. Use instead of brickognize_identify when you know the image shows a LEGO set.
Provide imagePath — absolute path to a local image file (JPEG, PNG, or WebP). Returns matched sets with set numbers, names, confidence scores, and links.
Inputs: imagePath, includeRaw.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools are mostly distinct with clear purposes: health check, general identification, and specialized identification for minifigures, parts, and sets. However, there is some overlap between brickognize_identify and the specialized tools, as the general tool can also identify these items, potentially causing confusion about when to use which. The descriptions help clarify, but the overlap exists.
All tool names follow a consistent pattern: they start with 'brickognize_' followed by a verb or verb phrase (e.g., 'health', 'identify', 'identify_fig', 'identify_part', 'identify_set'). This snake_case naming is uniform across all tools, making them predictable and easy to understand.
With 5 tools, the count is well-scoped for the server's purpose of LEGO item recognition. It includes a health check and multiple identification tools covering different item types, which is appropriate and manageable without being too sparse or overwhelming.
The tool set covers the core functionality of checking service health and identifying various LEGO items (general, minifigures, parts, sets), which aligns well with the domain. A minor gap is the lack of tools for additional operations like batch processing or detailed metadata retrieval, but the provided tools support the main workflows effectively.
Maintenance
Related MCP Connectors
Image processing over MCP: compress and split images, generate images and QR codes.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
OCR.space MCP — wraps the OCR.space API (ocr.space) for image/PDF → text OCR.
AI-powered image processing via GPU. Remove backgrounds and upscale images (2x/4x) directly from any MCP client. OAuth 2.1 authenticated, returns processed images inline with download links. Free credits on signup at maskr.io.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides OCR services powered by Google's Gemini API to extract text from images via file paths or base64 strings. It enables high-accuracy text recognition and CAPTCHA processing through simple MCP tools.8-
- AlicenseNot gradedqualityCmaintenanceEnables image analysis via OpenAI-compatible vision APIs, supporting local files, URLs, and base64 inputs with intelligent tiling for high-resolution images. Provides a secure, configurable MCP stdio server for structured vision analysis.91 npm3MIT
- AlicenseAqualityDmaintenanceProvides image recognition capabilities to MCP clients by integrating with OpenAI-compatible vision models, supporting local images, URLs, multi-image comparison, and model listing.4MIT
- AlicenseNot gradedqualityDmaintenanceProvides image understanding capabilities via local OCR and cloud VLM, enabling text extraction and visual description through MCP.5 npm2MIT