amazon-mcp

CLI + servidor MCP para o histórico de compras da sua conta na Amazon.com.br: pedidos, produtos, preço pago, frete, promoções, pontos de recompensa, parcelamento, notas fiscais e resumos de gastos, com cache local em SQLite para você perguntar quanto gastou sem bater na Amazon a cada pergunta.

A Amazon não tem API de comprador. A SP-API é para vendedores e a Product Advertising API é para afiliados; nenhuma dá acesso ao histórico da sua própria conta. Este projeto lê as mesmas páginas de pedidos que o seu navegador lê, autenticado pelos cookies da sua sessão. E precisa de um Chrome de verdade para isso: a Amazon.com.br entrega cada pedido cifrado dentro do HTML, e só o JavaScript da própria página o decifra (ADR-0009). Somente leitura: nenhuma operação de escrita na conta é implementada, e o escape hatch recusa qualquer caminho fora das páginas de pedidos.

$ amazon spending --by year
key   orders  items  total
----  ------  -----  ----------
2026  2       4      BRL 114.06
2025  1       1      BRL 210.99

Sumário

• Instalação

• Login

• Uso — CLI

• Uso — MCP

• Variáveis de ambiente

• Tools

• Como funciona

• Troubleshooting

• Documentação

• Licença

Related MCP server: Amazon Orders MCP

Instalação

Requer Bun 1.3 ou mais novo (o cache usa bun:sqlite) e o Google Chrome instalado.

Tudo de uma vez (Claude Code)

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

setup compila o binário para ~/.local/bin/amazon, registra o servidor MCP amazon no seu ~/.claude.json e instala a skill em ~/.claude/skills/. Rode de novo para atualizar.

npm

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

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

Binário único

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

O binário faz tudo, inclusive o login: o playwright-core vai embutido, e o Chrome vem do sistema.

Login

A senha nunca passa por aqui. Dois caminhos:

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

O segundo é o mais rápido se você já usa a Amazon 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/amazon-mcp/session.enc (0600). Detalhes em docs/LOGIN.md.

Uso — CLI

amazon status --verify              # a Amazon ainda aceita a sessão?
amazon sync --full                  # primeira carga (em blocos, 2 a 4 s por página)
amazon orders                       # pedidos do cache, do mais novo para o mais antigo
amazon order 702-1234567-1234567    # um pedido inteiro, com todos os subtotais
amazon search "amaciante"           # entre os produtos que você já comprou
amazon spending --by breakdown      # quanto foi produto, frete, promoção, pontos, imposto
amazon installments                 # parcelas projetadas, mês a mês
amazon invoice 702-1234567-1234567  # links de nota fiscal
amazon download-invoice 702-1234567-1234567   # salva o PDF da NF-e
amazon export --format csv --scope items      # para planilha
amazon doctor                       # qual camada quebrou

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

Uso — MCP

claude mcp add -s user amazon -- ~/.local/bin/amazon mcp

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

{
  "mcpServers": {
    "amazon": { "type": "stdio", "command": "/Users/voce/.local/bin/amazon", "args": ["mcp"] }
  }
}

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "quanto gastei na Amazon este ano?", "em quantas vezes parcelei o último pedido?", "me manda a nota fiscal daquele livro".

Variáveis de ambiente

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

Tools

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

Como funciona

1. login guarda os cookies da sessão cifrados com AES-256-GCM, inclusive os HttpOnly e o csd-key, a chave que a página usa para decifrar os pedidos.

2. sync abre um Chrome headless, percorre a lista de pedidos ano a ano e depois a página de detalhe de cada pedido, em blocos retomáveis. O transporte espera a descriptografia terminar e guarda o HTML já legível.

3. Tudo é normalizado para um modelo com dinheiro em centavos inteiros e gravado em SQLite. As perguntas depois disso são SQL local, sem rede.

4. Como o HTML descriptografado fica guardado, uma correção de parser reprocessa o passado com amazon sync --reparse, sem novas requisições.

Três regras vieram da conta real e são a espinha do projeto:

• O número do pedido só é lido de dentro do card. O cookie session-id tem a mesma forma e aparece em dezenas de URLs da página (ADR-0010).

• Zero pedidos só vale quando a página diz que o período está vazio. O filtro de período existe mesmo numa página que ainda não carregou.

• As parcelas são projeção: a Amazon informa quantas e de quanto, nunca as datas. installments_schedule marca isso em toda resposta.

Troubleshooting

Documentação

Licença

MIT. Uso pessoal, somente leitura, sobre a sua própria conta. Não redistribua os dados nem use isto como serviço multiusuário.