API de Lego: datos de sets, precios de tiendas y MCP para ChatGPT

Lego no ofrece una API pública para su catálogo ni para los precios de su tienda. Si quieres llevar datos de Lego a una app, una hoja de cálculo o un asistente de IA, tendrás que recurrir a servicios de terceros, y cada uno responde a una pregunta distinta. Rebrickable es la referencia para piezas e inventarios, Brickset para fichas de sets y colecciones, BrickLink para precios de su marketplace, nuevos o usados, y Brickfact para las ofertas actuales de las tiendas, con envío incluido, en nueve países. La API y el servidor MCP de Brickfact no piden clave.

Esta guía explica qué fuente sirve para cada tarea, muestra peticiones probadas contra la API JSON pública de Brickfact y detalla cómo conectar ChatGPT u otro asistente mediante el Model Context Protocol (MCP). Los ejemplos están pensados para España y usan euros. Brickfact gestiona este servicio, así que describimos sus límites con la misma franqueza que sus funciones.

¿Qué API de Lego encaja con tu proyecto?

Un inventario de piezas, un precio recomendado, una venta en un mercado y una oferta de tienda son cuatro cifras distintas. Decide primero cuál necesita tu proyecto y elige después el endpoint.

No es una clasificación: son herramientas para tareas distintas. Muchos proyectos acaban combinando dos fuentes: una de catálogo para las piezas y otra de precios para la compra. Lee las condiciones de cada servicio antes de empezar, porque los tres servicios fijan sus propias reglas.

Rebrickable: piezas, inventarios y el catálogo completo

La API de Rebrickable cubre los sets oficiales, las piezas y las minifiguras, además de colores, temas e inventarios de sets. Los usuarios con sesión iniciada también pueden leer y modificar su propia colección en Rebrickable. Cada llamada necesita una clave de API, que generas en los ajustes del perfil y envías en la cabecera Authorization: key … o como parámetro key.

La documentación aclara que no hay precios de sets ni de piezas. Para obtener el catálogo entero, Rebrickable pide usar sus archivos CSV descargables en vez de recorrer la API página a página. Una cuenta puede enviar de media una petición por segundo; si vas más rápido, recibirás errores HTTP 429.

Rebrickable es la opción para saber qué piezas tiene un set o en qué sets aparece una pieza concreta. No te dirá cuánto cuesta un set en ningún sitio.

Brickset: fichas de sets, colecciones y precios recomendados

La API de Brickset, versión 3, devuelve fichas de sets, temas y subtemas, años, instrucciones, reseñas e imágenes adicionales. Con el inicio de sesión de un usuario, lee y actualiza su colección en Brickset. La clave es obligatoria y se solicita en Brickset tras iniciar sesión.

Una clave nueva permite 100 llamadas diarias a getSets, suficiente para hacer pruebas. Para un proyecto en producción, Brickset pide que solicites un límite mayor, y su página sobre los servicios web prohíbe crear webs que copien Brickset. Las fichas incluyen el precio recomendado por Lego en Estados Unidos, Reino Unido, Canadá y Alemania, pero no en España. Es un precio recomendado, no lo que cobran hoy las tiendas.

BrickLink: precios de mercado de sets nuevos o usados

La API de BrickLink está pensada sobre todo para vendedores y da acceso también a la guía de precios de BrickLink. Las peticiones se firman al estilo de OAuth 1.0, con una clave y un secreto de consumidor, y los tokens de acceso solo valen para direcciones IP fijas registradas. Desde otra dirección el acceso falla, lo que descarta la mayoría de configuraciones en el navegador o serverless.

La guía de precios distingue entre las ventas de los últimos seis meses (guide_type=sold) y los anuncios actuales (stock), el estado nuevo o usado, la región y la moneda, y sus precios no incluyen IVA. Es la fuente adecuada para saber por cuánto se venden los ejemplares usados. Dónde comprar hoy el set nuevo y con envío a casa es otra pregunta.

Brickfact: las ofertas actuales de las tiendas en nueve países

La API pública de Brickfact devuelve las ofertas que Brickfact monitoriza en las tiendas: precio del artículo, gastos de envío declarados y total en la moneda del país de destino elegido. Cubre la búsqueda de sets, las características, las ofertas, las comparativas, el historial de precios registrado en tiendas, la valoración de una oferta y los sets parecidos. La API JSON y el servidor MCP usan el mismo código, así que tu programa y un asistente ven los mismos datos.

Estas rutas de solo lectura no piden cuenta de Brickfact ni clave de API. Eso no significa uso ilimitado ni la promesa de un servicio gratuito para siempre. Es un servicio compartido con un límite global de peticiones; con mucha carga responde con HTTP 429 y una cabecera Retry-After. Llámalo desde un servidor, un script o un notebook: las peticiones de navegador que vienen de otras webs se rechazan con invalid_origin.

El mercado es obligatorio en cada petición: decide qué tiendas cuentan y en qué moneda llegan los precios. Otros países, Portugal por ejemplo, se rechazan en lugar de sustituirse por un vecino. El parámetro opcional language solo cambia nombres y etiquetas. Una petición al mercado español con "language": "en" sigue devolviendo euros, tiendas españolas y un enlace a la página de comparación española.

Tu primera petición: sets de Lego hasta 50 € con envío

Esta petición busca en el mercado español sets de orquídeas con un total conocido, envío incluido, de 50 € como máximo:

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

Respuesta abreviada de una prueba del 30 de octubre de 2026. Los precios cambian, así que tus valores serán otros:

{
  "market": "ES",
  "currency": "EUR",
  "price_basis": "delivered",
  "sets": [
    {
      "set_id": 10311,
      "name": "Orquídeas",
      "theme": "Icons",
      "pieces": 608,
      "comparison_url": "https://brickfact.com/es-es/sets/lego-icons-orquídeas-10311",
      "item_price": null,
      "total_price": 47.99,
      "rrp": 49.99
    }
  ],
  "page": 1,
  "total": 3
}

Ojo con las tildes: en nuestras pruebas, «orquídea» encontraba los sets y «orquidea» sin tilde no devolvía nada. Si no estás seguro del nombre exacto, busca por número de set, que es lo más fiable.

La búsqueda también acepta theme_ids, rangos de número de piezas, edades como "18+", filtros de sets que se retiran pronto o ya retirados, orden por precio, descuento o novedad, y páginas de hasta 20 resultados. Los identificadores de tema salen de GET /api/v1/themes?market=ES&query=Star. Un campo desconocido devuelve HTTP 400 en vez de ignorarse, así que una errata no amplía tu búsqueda sin que te enteres.

La misma búsqueda en Python, con un presupuesto de 40 €, solo necesita la biblioteca estándar:

import json
import urllib.request

payload = {
    "market": "ES",
    "query": "orquídea",
    "price_basis": "delivered",
    "max_price": 40,
    "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"])

Las ofertas de un set, con gastos de envío

Para ver las ofertas de un solo set, usa la ruta de ofertas con el número del set:

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

Cada oferta incluye item_price, shipping, total, currency, feed_updated_at y stock_status. Las ofertas con total conocido van primero, y la respuesta añade lowest_known_total y lowest_item_price. Cuando Brickfact no conoce los gastos de envío de una tienda, shipping y total valen null. Léelo como desconocido, nunca como gratis.

stock_status siempre vale not_verified. Un precio en un feed no demuestra que haya existencias, y el envío declarado corresponde a un solo set. Los umbrales de envío gratuito, los cupones y las reglas del carrito pueden cambiar el importe final; manda el importe del proceso de pago de la tienda.

El detalle de un set (GET /api/v1/sets/10311?market=ES) añade el precio recomendado, la edad indicada, el número de minifiguras, las medidas y una fecha estimada de retirada. Para comparar de dos a cuatro sets, envía POST /api/v1/compare con una lista en set_ids.

¿Precio del artículo o precio con envío?

Por defecto, price_basis vale "item". En este modo, el presupuesto y el orden usan solo el precio del set, item_price viene relleno y total_price queda en null. Un set de 45 € con 6,99 € de envío entra así en un presupuesto de 50 €, aunque recibirlo en casa te cueste más.

Con "delivered", Brickfact usa el total con el envío declarado al mercado elegido. Las ofertas con envío desconocido se descartan antes del filtro de precio, el recuento y la paginación: total y cada página solo incluyen sets con un total conocido, sin huecos entre páginas. La contrapartida es que una tienda que no declara sus gastos de envío desaparece por completo de estos resultados.

Para comprar, el precio con envío suele ser la opción más honesta. Un precio bajo en una tienda extranjera deja muchas veces de ser una ganga en cuanto se suma el envío a España, y por eso los coleccionistas suelen comparar con envío incluido. Reserva el modo artículo para vistas de catálogo en las que el envío no importa.

Dos tipos de historial de precios

Brickfact lleva dos historiales distintos, y confundirlos da respuestas equivocadas.

El historial de precios en tiendas (POST /api/v1/retail-history, herramienta MCP get_retail_price_history) guarda cada día el precio más bajo conocido con envío en las tiendas monitorizadas de un mercado, en su moneda. Amazon queda fuera, igual que los días con envío desconocido o estimado. Los días pasados se calculan con las reglas de envío actuales para el país. La respuesta indica observation_days y first_observed_day. Esta serie empezó el 12 de octubre de 2026: pedir un periodo largo no garantiza un historial largo. Revisa la cobertura antes de sacar conclusiones.

El historial de valor de mercado (GET /api/v1/sets/75192/history?market=ES&range=1Y, herramienta MCP get_price_history) es otra serie: valoraciones de sets precintados en euros. Muestra cuánto vale un set precintado a lo largo del tiempo; nuestro estudio sobre la inversión en Lego usa valoraciones así para los sets que siguen en las colecciones. Aunque pidas GB, US o CH, sigue en euros, y no es un historial de lo que cobran las tiendas.

La valoración de oferta (POST /api/v1/assess-deal, herramienta MCP assess_deal) compara la oferta actual más barata con envío, de un feed de menos de 48 horas, con el mínimo registrado en las tiendas. Responde at_or_below_recorded_low o above_recorded_low, con la diferencia en porcentaje. Sin al menos dos días registrados o con un historial de más de 48 horas responde insufficient_history, y sin una oferta utilizable no_delivered_offer. La oferta actual puede ser de Amazon aunque el historial lo excluya. Un resultado en el mínimo registrado no es un mínimo histórico absoluto ni dice nada del precio del mes que viene.

Conectar ChatGPT u otro asistente mediante MCP

El Model Context Protocol es un estándar abierto para conectar aplicaciones de IA con sistemas externos. En lugar de escribir tú las peticiones, dejas que el asistente descubra las herramientas de Brickfact y las llame cuando tu pregunta necesita datos actuales.

Para ChatGPT, la guía de conexión de OpenAI describe el camino actual: abre ChatGPT Plugins, pulsa el botón «+» y luego Add custom MCP server, ponle nombre y descripción, escribe la URL con /mcp, elige sin autenticación, confirma el aviso de riesgo y selecciona Create as a plugin. Se aplican las políticas de tu cuenta y de tu espacio de trabajo; en una empresa, el administrador decide si se permiten servidores MCP propios. Aparecer en el directorio público de plugins de ChatGPT requiere una revisión aparte de OpenAI; busca Brickfact en el directorio antes de dar por hecho que está.

Otros clientes compatibles con servidores remotos por Streamable HTTP se conectan con la misma URL. Los clientes locales que solo admiten stdio necesitan un puente.

Las once herramientas:

Qué pedirle al asistente para comprar

El servidor pide al asistente que tome el país de compra de la conversación y que lo pregunte si falta, así que menciónalo desde el principio. Estos prompts cubren las herramientas principales:

• «Busca sets de Lego Star Wars por menos de 100 € con envío a España y muéstralos como tarjetas.»
• «Ayúdame a elegir un regalo de Lego de hasta 60 € con envío en España para un niño de 10 años al que le gustan los coches.»
• «Compara los sets Lego 10311 y 10313 con entrega en España, con número de piezas y precio con envío.»
• «¿Es bueno el precio actual del set Lego 75192 en España frente a los precios registrados en tiendas? Dime cuántos días de datos tienes.»
• «Busca alternativas más baratas al set Lego 75192 con entrega en España.»

Los hosts compatibles con MCP Apps muestran tarjetas de sets con imágenes, una comparativa lado a lado y gráficos del historial de precios en tiendas. En otros, el asistente responde en texto con los mismos datos. Si el host deja que las apps guarden estado, la tarjeta puede conservar una lista de hasta seis números de set. Esa lista pertenece a la tarjeta dentro de la conversación, no a una cuenta de Brickfact, y puede que no esté en un chat nuevo.

Lo que el asistente no puede hacer

El servidor MCP solo lee datos públicos del catálogo. No puede comprar nada, no pide datos de pago, no ve tu colección de Brickfact y no cambia tu cuenta. Si le pides que te avise cuando el set Lego 10311 baje de 30 €, el asistente te devolverá un enlace a la app con "created": false: un enlace a la app de Brickfact y los pasos para crear allí la alerta. No se crea nada hasta que lo confirmas en la app. Si lo que buscas son descuentos del día, nuestra página de ofertas de Lego los reúne.

Los precios de una respuesta nunca son más recientes que el feed que los alimenta. Una buena oferta puede agotarse minutos después de una bajada, así que abre el enlace de comparación devuelto y revisa la tienda antes de comprar.

Buenas prácticas para tu integración

Unas cuantas costumbres evitan errores cuando cambian los datos:

• Empieza con un set y un mercado, y comprueba la moneda y price_basis en cada respuesta antes de añadir más países.
• Muestra un envío null como desconocido, sin cambiarlo por cero.
• Indica feed_updated_at o la hora de tu petición junto a los precios.
• Trata los resultados vacíos y los historiales cortos como respuestas normales, no como errores.
• Guarda las respuestas en caché unos minutos, respeta Retry-After y no recorras todo el catálogo a base de páginas de búsqueda.
• Enlaza la comparison_url devuelta en lugar de construir tú las direcciones de las páginas de sets.

Los esquemas de entrada de todas las rutas están en el endpoint público de esquemas. Si prefieres comparar precios a mano, el catálogo de Lego muestra las mismas ofertas con filtros, y cómo comparamos precios explica qué tiendas monitorizamos.

Una API para programar hubs y motores de Lego es cosa de robótica, no de datos: nuestra guía para programar un robot Lego trata SPIKE, Mindstorms y Python con Pybricks. Brickfact es independiente del Grupo Lego.