mercadolivre-mcp

CLI + servidor MCP para o histórico de compras da sua conta do Mercado Livre (lado comprador): compras, produtos, preço cheio e pago, descontos e cupons, parcelamento, meio de pagamento, vendedor, entrega e notas fiscais (NF-e em PDF e XML), com cache local em SQLite para responder "quanto gastei em 2025 com limpeza?" sem bater no site a cada pergunta.

O Mercado Livre não tem API pública do lado comprador: a API oficial é para vendedores e responde 403 ao resto. Este projeto lê a mesma superfície web que o seu navegador usa (as páginas de "Minhas compras" e o endpoint das NF-e), autenticado pelos cookies da sua própria sessão. Somente leitura: nenhuma operação de escrita na conta existe, e o raw_get só faz GET em dois hosts do site.

Sumário

• Instalação

• Login

• Uso — CLI

• Uso — MCP

• Variáveis de ambiente

• Tools

• Como funciona

• Troubleshooting

• Documentação

• Licença

Instalação

Requer Bun 1.3 ou mais novo (o cache usa bun:sqlite).

Tudo de uma vez (Claude Code)

git clone https://github.com/maxwellmezadre/mercadolivre-mcp.git
cd mercadolivre-mcp
bun install
bun run setup

O setup compila o binário para ~/.local/bin/mercadolivre, registra o servidor MCP mercadolivre no seu ~/.claude.json (escopo de usuário, com caminho absoluto) e instala a Skill em ~/.claude/skills/mercadolivre-mcp/. Rode de novo para atualizar. Com --import-browser chrome o registro já sai com MERCADOLIVRE_IMPORT_BROWSER=chrome.

npm

npm i -g @maxwellmezadre/mercadolivre-mcp   # instala `mercadolivre` e `mercadolivre-mcp` no PATH
mercadolivre --version

O pacote roda com o Bun (por causa do bun:sqlite), então o Bun precisa estar instalado. Sem instalar nada:

bunx -p @maxwellmezadre/mercadolivre-mcp mercadolivre purchases

O -p e o nome do executável são necessários: o pacote declara dois binários e, sem eles, bunx @maxwellmezadre/mercadolivre-mcp executa o homônimo do pacote, que é o servidor MCP, e não a CLI.

Binário único

bun run build:binary   # gera ./mercadolivre, sem precisar de runtime instalado
./mercadolivre --version

O binário embute tudo, inclusive o playwright-core que o login usa. Os binários de cada Release são esses mesmos, para Linux, macOS e Windows.

Login

A senha nunca passa por aqui. Dois caminhos:

mercadolivre login                        # abre o seu navegador padrão para você entrar
mercadolivre login --from-browser chrome  # importa a sessão de um navegador já logado (macOS)

O primeiro abre o navegador padrão do sistema, que precisa ser o Google Chrome ou outro Chromium que exponha o DevTools (Brave, Edge, Vivaldi, Chromium). Safari e Firefox são outros motores, e o Arc não aceita automação: nesses casos a ferramenta avisa e usa outro navegador compatível que já esteja instalado. O segundo é o mais rápido se você já usa o site no Chrome, no Arc, no Brave ou no Edge: ele lê os cookies pelo Keychain (o macOS pede permissão uma vez) e não abre janela nenhuma.

A sessão é gravada cifrada com AES-256-GCM em ~/.config/mercadolivre-mcp/session.enc (0600). Sem navegador nenhum, MERCADOLIVRE_COOKIE aceita o header Cookie copiado do DevTools. Detalhes em docs/LOGIN.md.

Uso — CLI

mercadolivre status --verify             # o site ainda aceita a sessão?
mercadolivre sync --full                 # primeira carga: ~3 min para ~70 compras
mercadolivre purchases --date 3M         # compras dos últimos 3 meses, do cache
mercadolivre purchase 2000000000000001   # detalhe: financeiro, parcelas, produtos, vendedor, NF-e
mercadolivre search "café"               # entre os produtos que você já comprou
mercadolivre products --seller "gallo"   # produtos comprados, com preço pago e unitário
mercadolivre product-history --title "azeite"
mercadolivre spending --by month         # quanto você gastou por mês
mercadolivre installments                # parcelas em aberto (estimativa)
mercadolivre export --format csv --scope products
mercadolivre export-invoices --date Y    # NF-e do ano em PDF e XML
mercadolivre doctor                      # qual camada quebrou

Todo comando aceita --json e imprime exatamente o que o cliente MCP receberia. Referência completa em docs/CLI.md.

Uso — MCP

claude mcp add -s user mercadolivre -- /Users/você/.local/bin/mercadolivre mcp

Ou, à mão, em ~/.claude.json:

{
  "mcpServers": {
    "mercadolivre": {
      "type": "stdio",
      "command": "/Users/você/.local/bin/mercadolivre",
      "args": ["mcp"]
    }
  }
}

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "quanto gastei no Mercado Livre este ano?", "quantas vezes comprei esse café e a que preço?", "me manda as notas fiscais de 2025".

Variáveis de ambiente

Todas opcionais. A tabela completa está em docs/CONFIGURATION.md.

Nomes antigos (MERCADOLIVRE_HOME, MERCADOLIVRE_DOWNLOAD_DIR, MERCADOLIVRE_REQUEST_INTERVAL_MS, MERCADOLIVRE_REAL) continuam funcionando com um aviso.

Tools

São 18, iguais no MCP e no CLI. Referência gerada: docs/TOOLS.md.

Como funciona

1. A lista de compras é uma página server-side (Nordic/Flox) com o JSON embutido em <script id="__NORDIC_RENDERING_CTX__">; os parsers leem esse JSON, nunca o HTML.

2. Uma compra (purchase_id) contém pacotes (pack_id) que contêm pedidos (order_id), e cada pedido é um produto. Tudo é agregado por compra: contar pedidos como compras infla o número por cerca de 3 vezes. Ver docs/DATA-MODEL.md.

3. O sync percorre as páginas a uma requisição a cada 1,2 a 1,6 segundos, busca o detalhe de cada compra uma única vez, as NF-e e as categorias, e grava tudo em SQLite com dinheiro em centavos inteiros. As demais tools consultam o cache.

4. Quando o site mudar, doctor diz qual endpoint quebrou e raw_get mostra o payload real; o roteiro está em docs/REDISCOVERY.md.

Troubleshooting

Documentação

Licença

MIT. Uso pessoal, na sua própria conta, em volume baixo: sem revenda de dados, sem compartilhar a sessão, sem coletar dados de terceiros.