retailerapi

@retailerapi/mcp

Servidor de Protocolo de Contexto de Modelo (MCP) para retailerapi.com — uma API unificada de dados de produtos que cobre as principais varejistas dos EUA. Duas ferramentas que seu agente de IA pode chamar diretamente: consultas de produtos e ofertas ao vivo.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer outro cliente compatível com MCP via stdio.

Varejistas cobertos: Walmart, Amazon, eBay, Target, Best Buy, Lowe's, Home Depot. Defina include_cross_retailer=true em uma consulta de produto para exibir células em cache de cada varejista que temos para esse UPC.

Início rápido

1. Obtenha uma chave de API

Entre em app.retailerapi.com e crie uma chave na página API Keys. As chaves têm o formato rk_live_…. O plano gratuito oferece 1.000 consultas/mês — sem cartão de crédito.

2. Adicione o servidor ao seu cliente MCP

Claude Desktop

Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) e adicione:

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

Reinicie o Claude Desktop. As ferramentas do retailerapi aparecerão no seletor de ferramentas.

Claude Code

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

Cursor

Adicione em ~/.cursor/mcp.json (ou no .cursor/mcp.json de nível de projeto):

{
  "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

O processo fala MCP via stdio (JSON-RPC delimitado por nova linha em stdin/stdout). Os logs vão para stderr.

Ferramentas

lookup_product

Resolva qualquer identificador (UPC / EAN / ISBN / GTIN / ASIN da Amazon / item_id do varejista) em um resumo normalizado do produto. Chamada base (1 token) retorna: título, marca, imagem, preço atual, identificadores, peso, dimensões, preço sugerido, descrição, categorias, histórico completo de preços, estatísticas agregadas, retailer_links (grátis 'onde encontrar'), fatos do Bucket-1 (sold_tag, estimated_sales, is_best_seller, pack_count, hazmat) e taxas de marketplace calculadas (referral_fee_usd, wfs_fee_usd). As taxas são GRÁTIS na chamada base — paridade com Keepa.

Defina include_cross_retailer=true para adicionar o bloco cross_retailer — um mapa chaveado por slug do varejista com células em cache por varejista (preço, in_stock, campos do Bucket-1) para cada varejista que temos para este UPC (+2 tokens). Somente leitura sobre nosso cache. Defina include_seller_context=true para adicionar estado ao vivo do lado do vendedor (is_restricted, elegibilidade WFS) em varejistas de marketplace (+3 tokens).

Para forçar uma nova coleta de um varejista específico (ignorando o cache), chame com retailer=<slug> e force_refresh=true. Esta é a única forma de forçar dados atualizados da API.

Consultas de código de barras também retornam um bloco de diagnóstico _meta com o varejista de origem para cada campo de nível superior (incluindo weight_lbs_source e dimensions_source — útil quando o catálogo de um varejista não tem especificações físicas e outro varejista as preenche) e um data_quality_score (0.0–1.0).

Pacote vs. montado. Varejistas que distinguem peso embalado para envio do peso do produto preenchem weight_assembled_lbs + weight_package_lbs (e os paralelos dimensions_assembled + dimensions_package). Os weight_lbs / dimensions de nível superior são os derivados "melhor disponível" — montado vence, pacote preenche, peso simples é o último recurso. Varejistas que expõem apenas um peso preenchem weight_lbs e deixam o par explícito como null.

Campo	Tipo
identifier	string (obrigatório)
identifier_type	"UPC" | "EAN" | "ISBN" | "GTIN" | "ASIN" | "item_id" (opcional — detecção automática se omitido)
include_cross_retailer	boolean (opcional — padrão false) — +2 tokens, somente leitura
include_seller_context	boolean (opcional — padrão false) — +3 tokens
retailer	string (opcional) — âncora para um slug específico de varejista
force_refresh	boolean (opcional — padrão false) — somente válido com retailer; ignora cache + força nova coleta

Exemplos de prompts:

• "Consulte o UPC 045496590161 — qual é a marca, o preço e a taxa de referência do Walmart?"
• "Encontre o UPC 194629116676 em todos os varejistas — quem tem o preço mais barato?"
• "Qual é a taxa WFS deste produto? Há restrições de vendedor na Amazon?"

get_offers

Liste os vendedores atuais do marketplace em um produto, incluindo preço, estado de estoque e qual vendedor possui a buy box.

Campo	Tipo
item_id	string (obrigatório)

Exemplo de prompt: "Quem tem a buy box no item 1689065034 e qual é o próximo vendedor mais barato?"

Erros

As chamadas de ferramenta retornam erros JSON estruturados em vez de travar o agente:

Status	Código de erro	Significado
401, 403	unauthorized	Chave de API inválida ou escopo ausente. Verifique RETAILERAPI_KEY.
404	not_found	Produto ou item_id não encontrado.
429	rate_limited	Limite de cota ou rajada atingido. Inclui retry_after_seconds.
5xx	upstream_error	Problema no backend. Tente novamente em breve.
—	missing_api_key	Variável de ambiente RETAILERAPI_KEY não definida. Ponteiro para a documentação incluído.

Ambiente

Variável	Obrigatória	Padrão
RETAILERAPI_KEY	sim	—
RETAILERAPI_BASE_URL	não	https://api.retailerapi.com/v1

Desenvolver localmente

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

O MCP Inspector (npx @modelcontextprotocol/inspector) é a maneira mais fácil de exercitar as ferramentas manualmente.

Licença

MIT