Lego API: set data, retailer prices and MCP for ChatGPT

Lego does not offer a public developer API for its catalogue or its shop prices. If you want Lego data in an app, a spreadsheet or an AI assistant, you work with third-party sources, and each of them answers a different question. Rebrickable is the place for parts and inventories, Brickset for set records and collections, BrickLink for marketplace prices, and Brickfact for current shop offers with shipping in nine countries. Brickfact's API and MCP server need no key.

This guide explains which source fits which job, shows tested requests against Brickfact's public JSON API, and walks through connecting ChatGPT or another assistant through the Model Context Protocol (MCP). The examples use US dollars and pounds sterling. Brickfact runs this service, so we describe its limits as plainly as its features.

Which Lego API fits your project?

A parts inventory, a recommended retail price, a marketplace sale and a shop offer are four different numbers. Decide which one your project needs before you choose an endpoint.

These are tools for different jobs, not a ranking. Many projects end up combining two: a catalogue source for parts and a price source for shopping. Check each provider's terms before you build on it, because all three services set their own usage rules.

Rebrickable: parts, inventories and the full catalogue

Rebrickable's API covers official sets, parts and minifigures, colours, themes and set inventories. Logged-in users can also read and change their own Rebrickable collection. Every call needs an API key, which you generate in your profile settings and send in the Authorization: key … header or as a key parameter.

The documentation is explicit that there is no set or part pricing. For a full copy of the catalogue, Rebrickable asks developers to use its CSV downloads instead of paging through the API. Accounts can send about one request per second on average; faster clients get HTTP 429 responses.

Choose Rebrickable when the question is "which pieces are in this set?" or "which sets contain this part?". It will not tell you what a set costs anywhere.

Brickset: set records, collections and Lego retail prices

Brickset's API, version 3, returns set records, themes, subthemes, years, instructions, reviews and additional images. With a user's login it can also read and update that user's Brickset collection. A key is required; you request it on Brickset after logging in.

New keys can make 100 getSets calls a day, which suits testing. Brickset asks you to request a higher limit when your project goes into production, and its web services page rules out building copycat websites. Set records include Lego's own retail price for the US, the UK, Canada and Germany. That is a recommended retail price, not what shops charge today.

BrickLink: marketplace prices, new or used

The BrickLink API is mainly built for sellers, and it also exposes BrickLink's price guide. Requests use OAuth 1.0 style signatures with a consumer key and secret, and access tokens are issued for static IP addresses you register. Calls only work from those addresses, which rules out most browser and serverless setups.

The price guide separates sales from the last six months (guide_type=sold) from current listings (stock), covers new and used condition, region and currency, and its prices exclude VAT. That is the right source for "what do used copies of this set sell for?". It answers a different question from "where can I buy it new today, delivered to my door?".

Brickfact: current shop offers in nine countries

Brickfact's public API returns the offers Brickfact monitors at retailers, with item price, reported shipping and total in the currency of the destination you choose. It covers set search, specifications, offers, comparisons, recorded retail price history, deal checks and related sets. The JSON API and the MCP server use the same handlers, so an assistant and your own code see the same data.

You need no Brickfact account or API key for these read-only routes. That does not mean unlimited use or a promise that the service stays free forever. It is a shared service with a global request limit, and busy moments return HTTP 429 with a Retry-After header. Call it from a server, script or notebook: browser requests from other websites are rejected with invalid_origin.

The market is required in every request, and it decides which retailers count and which currency you get. Other countries are rejected rather than mapped to a neighbour. The optional language parameter only changes names and labels. A German market request with "language": "en" still returns euros, German retailers and a link to the German comparison page.

Your first request: Lego sets for £60 or less delivered

This request searches the UK market for orchid sets with a known delivered total of £60 or less:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/search' \
  --header 'Content-Type: application/json' \
  --data '{"market":"GB","query":"orchid","price_basis":"delivered","max_price":60,"limit":3}'

Shortened response from a test on 30 October 2026. Prices change, so yours will differ:

{
  "market": "GB",
  "currency": "GBP",
  "price_basis": "delivered",
  "sets": [
    {
      "set_id": 10311,
      "name": "Orchid",
      "theme": "Icons",
      "pieces": 608,
      "comparison_url": "https://brickfact.com/en-gb/sets/lego-icons-orchid-10311",
      "item_price": null,
      "total_price": 31.99,
      "rrp": 44.99
    }
  ],
  "page": 1,
  "total": 3
}

Search also accepts theme_ids, piece ranges, age labels such as "18+", retirement filters, sorting by price, discount or newest, and pages of up to 20 results. Theme IDs come from GET /api/v1/themes?market=US&query=Star. Unknown fields fail with HTTP 400 instead of being ignored, so a typo does not silently widen your search.

The same search in Python, for a US budget of $50, needs only the standard library:

import json
import urllib.request

payload = {
    "market": "US",
    "query": "orchid",
    "price_basis": "delivered",
    "max_price": 50,
    "limit": 5,
}
request = urllib.request.Request(
    "https://mcp.brickfact.com/api/v1/search",
    data=json.dumps(payload).encode(),
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)

for item in result["sets"]:
    print(item["set_id"], item["name"], item["total_price"], result["currency"])

Offers for one set, with shipping

For the offers on one set, use the offers route with the set number:

curl --fail --silent --show-error \
  'https://mcp.brickfact.com/api/v1/sets/10311/offers?market=US&price_basis=delivered'

Each offer carries item_price, shipping, total, currency, feed_updated_at and stock_status. Offers with a known delivered total come first, and the response adds lowest_known_total and lowest_item_price. When a shop's shipping fee is unknown, shipping and total are null. Treat that as unknown, never as free.

stock_status is always not_verified. A feed listing a price does not prove the set is in stock, and the reported shipping is the fee for a single set. Free-shipping thresholds, vouchers and checkout rules can change the final amount, so the shop's checkout has the last word.

Set details (GET /api/v1/sets/10311?market=GB) add the recommended retail price, age label, minifigure count, dimensions and an estimated retirement date. Comparing two to four sets works with POST /api/v1/compare and a set_ids list.

Item price or delivered price?

The default price_basis is "item". In this mode budgets and sorting use the price of the set alone, item_price is filled and total_price stays null. A set listed at $45 with $6.99 shipping passes a $50 item budget even though it costs more than $50 at your door.

With "delivered", Brickfact uses the total including reported shipping to the selected market. Offers with unknown shipping are removed before the price filter, the result count and pagination, so total and every page only include sets with a known delivered total, and filtering never leaves gaps between pages. The trade-off: a shop that does not report shipping drops out of delivered results entirely.

For shopping, delivered is usually the honest choice. A low item price from a shop abroad often stops being a bargain once shipping to your country is added, which is why collectors tend to compare prices including delivery. Keep the item mode for catalogue views where shipping does not matter.

Two kinds of price history

Brickfact has two history datasets, and mixing them up gives wrong answers.

Retail price history (POST /api/v1/retail-history, MCP tool get_retail_price_history) records the lowest known delivered price per day at the monitored retailers of one market, in that market's currency. Amazon is excluded, and so are days with unknown or estimated shipping. Past days are priced with today's shipping rules for the destination. The response states observation_days and first_observed_day. This series only began on 12 October 2026, so a long requested window does not mean a long record; read the coverage before you draw conclusions.

Market valuation history (GET /api/v1/sets/75192/history?market=US&range=1Y, MCP tool get_price_history) is a separate series of sealed-set valuations in euros. It answers what a sealed set is worth over time, the kind of value our Lego market-performance study analyses. Asking for the US market does not convert it to dollars, and it is not a record of shop prices.

The deal check (POST /api/v1/assess-deal, MCP tool assess_deal) compares the cheapest current delivered offer, from a feed no older than 48 hours, with the recorded retail low. It returns at_or_below_recorded_low or above_recorded_low with the difference in percent. Without at least two recorded days and history no older than 48 hours it returns insufficient_history, and without a usable offer no_delivered_offer. The current offer may come from Amazon even though the history excludes it. A result at the recorded low is not an all-time low and says nothing about next month's price.

Connect ChatGPT or another assistant via MCP

The Model Context Protocol is an open standard for connecting AI applications to external systems. Instead of writing requests yourself, an assistant discovers Brickfact's tools and calls them when your question needs live data.

In ChatGPT, OpenAI's connection guide describes the current route: open ChatGPT Plugins, select the plus button and Add custom MCP server, give it a name and description, enter the URL including /mcp, choose no authentication, confirm the risk warning and select Create as a plugin. Account and workspace policies apply, so in a company workspace your admin decides whether custom MCP servers are allowed. Listing in ChatGPT's public plugin directory is a separate review by OpenAI, so search the directory for Brickfact before assuming you will find it there.

Other clients that support remote Streamable HTTP servers connect with the same URL. Local-only clients that speak stdio need a bridge.

The eleven tools:

Shopping prompts that work

The server asks the assistant to use the shopping country from your conversation and to ask when it is missing, so name it. These prompts cover the main tools:

• "Find Lego Star Wars sets under $100 including shipping to the United States and show them as cards."
• "Help me choose a Lego gift under £60 delivered in the UK for a 10-year-old who likes cars."
• "Compare Lego 10311 and 10313 for delivery to the UK, with piece counts and delivered prices."
• "Is today's price for Lego 75192 in the US good compared with recorded retail prices? Tell me how many days of data you have."
• "Find cheaper alternatives to Lego 75192 delivered in the UK."

Hosts that support MCP Apps show set cards with images, a side-by-side comparison and retail-history charts. Elsewhere the assistant answers in text with the same data. Where the host lets apps keep state, the card can hold a shortlist of up to six set numbers. That shortlist lives in the conversation's card, not in a Brickfact account, and may not carry over to a new chat.

What the assistant cannot do

The MCP server reads public catalogue data only. It cannot buy anything, ask for payment details, see your Brickfact collection or change your account. Ask it to "notify me when Lego 10311 drops below $35" and you get an app handoff with "created": false: a link to the Brickfact app and the steps to set the alert there. Nothing is created until you confirm it in the app. If alerts are what you are after, our guide to the Lego price tracker covers that side.

Prices in an answer are only as current as the feed behind them. A good deal can sell out minutes after a price drops, so open the returned comparison link and check the shop before you buy.

Habits that keep an integration accurate

A few habits keep an integration correct when the data changes:

• Start with one set and one market, and check currency and price_basis in every response before adding more destinations.
• Keep null shipping as unknown in your interface. Do not replace it with zero.
• Show feed_updated_at or the date of your request next to prices.
• Treat empty results and short histories as normal answers, not errors.
• Cache responses for a few minutes, respect Retry-After and avoid crawling the whole catalogue through search pages.
• Link the returned comparison_url rather than building set page URLs yourself.

Input schemas for every route are at the public schema endpoint. If you prefer to compare prices by hand, the Lego database has the same offers with filters, and how we compare prices explains which retailers we monitor.

An API for programming Lego hubs and motors is a robotics question rather than a data one: our guide to Lego robotics programming covers SPIKE, Mindstorms and Python with Pybricks. Brickfact is independent of the Lego Group.