retailerapi

@retailerapi/mcp

Servidor de Protocolo de Contexto de Modelo para retailerapi.com — una API unificada de datos de productos que cubre los principales minoristas de EE. UU. Dos herramientas que tu agente de IA puede llamar directamente: búsquedas de productos y ofertas en vivo.

Funciona con Claude Desktop, Claude Code, Cursor y cualquier otro cliente compatible con MCP a través de stdio.

Minoristas cubiertos: Walmart, Amazon, eBay, Target, Best Buy, Lowe's, Home Depot. Establece include_cross_retailer=true en una búsqueda de producto para mostrar celdas en caché para cada minorista que tengamos para ese UPC.

Inicio rápido

1. Obtén una clave de API

Inicia sesión en app.retailerapi.com y crea una clave en la página API Keys. Las claves se ven como rk_live_…. El plan gratuito incluye 1,000 búsquedas al mes — sin tarjeta.

2. Añade el servidor a tu cliente MCP

Claude Desktop

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) y añade:

{
  "mcpServers": {
    "retailerapi": {
      "command": "npx",
      "args": ["-y", "@retailerapi/mcp"],
      "env": {
        "RETAILERAPI_KEY": "rk_live_your_key_here"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de retailerapi aparecerán en el selector de herramientas.

Claude Code

claude mcp add retailerapi npx -y @retailerapi/mcp \
  --env RETAILERAPI_KEY=rk_live_your_key_here

Cursor

Añade a ~/.cursor/mcp.json (o al .cursor/mcp.json a nivel de proyecto):

{
  "mcpServers": {
    "retailerapi": {
      "command": "npx",
      "args": ["-y", "@retailerapi/mcp"],
      "env": {
        "RETAILERAPI_KEY": "rk_live_your_key_here"
      }
    }
  }
}

stdio genérico

RETAILERAPI_KEY=rk_live_your_key_here npx @retailerapi/mcp

El proceso habla MCP a través de stdio (JSON-RPC delimitado por nuevas líneas en stdin/stdout). Los registros van a stderr.

Herramientas

lookup_product

Resuelve cualquier identificador (UPC / EAN / ISBN / GTIN / ASIN de Amazon / item_id de minorista) en un resumen de producto normalizado. Llamada base (1 token) devuelve: título, marca, imagen, precio actual, identificadores, peso, dimensiones, MSRP, descripción, categorías, historial de precios completo, estadísticas agregadas, retailer_links (gratis 'dónde encontrarlo'), hechos de Bucket-1 (sold_tag, estimated_sales, is_best_seller, pack_count, hazmat) y tarifas de marketplace calculadas (referral_fee_usd, wfs_fee_usd). Las tarifas son GRATIS en la llamada base — paridad con Keepa.

Establece include_cross_retailer=true para añadir el bloque cross_retailer — un mapa claveado por slug de minorista de celdas en caché por minorista (price, in_stock, campos de Bucket-1) para cada minorista que tengamos para este UPC (+2 tokens). Solo lectura sobre nuestra caché. Establece include_seller_context=true para añadir estado en vivo del lado del vendedor (is_restricted, elegibilidad WFS) en minoristas de marketplace (+3 tokens).

Para forzar un raspado fresco de un minorista específico (omitiendo la caché), llama con retailer=<slug> y force_refresh=true. Esta es la única forma de forzar datos frescos desde la API.

Las búsquedas por código de barras también devuelven un bloque de diagnóstico _meta con el minorista de origen para cada campo de nivel superior (incluyendo weight_lbs_source y dimensions_source — útil cuando el catálogo de un minorista carece de especificaciones físicas y otro minorista las completa) y un data_quality_score (0.0–1.0).

Paquete vs ensamblado. Los minoristas que distinguen el peso empaquetado para envío del peso del producto completan weight_assembled_lbs + weight_package_lbs (y los paralelos dimensions_assembled + dimensions_package). Los weight_lbs / dimensions de nivel superior son el "mejor disponible" derivado — el ensamblado gana, el paquete rellena, el peso simple es el último recurso. Los minoristas que exponen solo un peso completan weight_lbs y dejan el par explícito como null.

Campo	Tipo
identifier	cadena (obligatorio)
identifier_type	"UPC" | "EAN" | "ISBN" | "GTIN" | "ASIN" | "item_id" (opcional — auto-detect si se omite)
include_cross_retailer	booleano (opcional — por defecto false) — +2 tokens, solo lectura
include_seller_context	booleano (opcional — por defecto false) — +3 tokens
retailer	cadena (opcional) — ancla a un slug de minorista específico
force_refresh	booleano (opcional — por defecto false) — solo válido con retailer; omitir caché + forzar raspado fresco

Ejemplos de prompts:

• "Busca el UPC 045496590161 — ¿cuál es la marca, el precio y la tarifa de referencia de Walmart?"
• "Encuentra el UPC 194629116676 en todos los minoristas — ¿quién lo tiene más barato?"
• "¿Cuál es la tarifa WFS de este producto? ¿Hay restricciones de vendedor en Amazon?"

get_offers

Lista los vendedores actuales del marketplace en un producto, incluyendo precio, estado de disponibilidad y qué vendedor posee la caja de compra.

Campo	Tipo
item_id	cadena (obligatorio)

Ejemplo de prompt: "¿Quién tiene la caja de compra en el artículo 1689065034 y cuál es el siguiente vendedor más barato?"

Errores

Las llamadas a herramientas devuelven errores JSON estructurados en lugar de bloquear al agente:

Estado	Código de error	Significado
401, 403	unauthorized	Clave de API inválida o sin alcance. Revisa RETAILERAPI_KEY.
404	not_found	Producto o item_id no encontrado.
429	rate_limited	Límite de cuota o ráfaga alcanzado. Incluye retry_after_seconds.
5xx	upstream_error	Problema de backend. Reintenta en breve.
—	missing_api_key	Variable de entorno RETAILERAPI_KEY no establecida. Se incluye puntero a la documentación.

Entorno

Variable	Requerida	Predeterminado
RETAILERAPI_KEY	sí	—
RETAILERAPI_BASE_URL	no	https://api.retailerapi.com/v1

Desarrollo local

pnpm install
pnpm --filter @retailerapi/mcp build
RETAILERAPI_KEY=rk_live_… node packages/mcp/dist/index.js

El Inspector MCP (npx @modelcontextprotocol/inspector) es la forma más fácil de probar las herramientas manualmente.

Licencia

MIT