mercadolivre-mcp

MCP server (stdio, uso pessoal): busca e detalhe de produtos no Mercado Livre Brasil via api.mercadolibre.com.

Tools: search_products (catálogo: keywords, GTIN ou domínio — sem preço), get_product (ficha + variações), get_item / get_items (preço por id de anúncio, bulk até 20), get_seller_items (anúncios com preço por seller_id), get_seller_profile (reputação/nível), browse_category (árvore de categorias), get_trends (termos em alta), get_item_questions (Q&A público), get_own_items (anúncios da própria conta).

Catálogo não tem preço — preço vive no anúncio. Fluxos típicos: search_products (descobre) → get_item com o id do link (preço); get_item → seller_id → get_seller_items + get_seller_profile. A busca pública /sites/*/search é bloqueada na borda para este app (IP de datacenter); o server nem tenta esse endpoint.

Pré-requisito: permissões funcionais do app

Só users vem ativo por padrão (dá acesso a /users/me). Todo o resto retorna 403 PolicyAgent até você ativar no DevCenter → seu app → permissões funcionais → leitura (produtos/itens). Depois reautorize o app (novo code), pois os grants mudam.

Related MCP server: mercadolibre-mcp

Env

Obter o primeiro refresh_token:

1. https://auth.mercadolivre.com.br/authorization?response_type=code&client_id=SEU_ID&redirect_uri=SUA_URI

2. Autorize → capture o ?code=... no redirect.

3. Troque (única vez): POST https://api.mercadolibre.com/oauth/token grant_type=authorization_code&client_id=…&client_secret=…&code=…&redirect_uri=…

Rotação: o refresh_token é de uso único — a cada refresh o server persiste o par novo em .ml-tokens.json (modo 600, gitignored). A cópia no .env fica obsoleta após a primeira rotação; fonte da verdade passa a ser o arquivo. access_token dura ~6h e é renovado sozinho (com retry único em 401).

Dev

npm install
npm test            # build + vitest (live pula sem ML_LIVE=1)
ML_LIVE=1 npm test  # inclui chamadas reais à API
npm run setup:hooks # pre-push: build + testes

Nota: available_quantity nos recursos públicos é referencial (faixas), não estoque exato. Nunca inventamos números: sem dados a tool retorna isError com a causa.