aliexpress-mcp

CLI + servidor MCP para o histórico de compras da sua conta do AliExpress: pedidos, produtos, breakdown de preço (imposto, frete, cupons, taxa de parcelamento), rastreio completo, devoluções e resumos de gastos, com cache local, para você perguntar quanto gastou sem bater no AliExpress a cada pergunta.

O AliExpress não tem API de comprador. A Open Platform dele é para afiliados, dropshipping e vendedores, e não dá acesso ao histórico da sua própria conta. Este projeto fala a API interna que o próprio site usa (MTOP, em acs.aliexpress.com), autenticado pelos cookies da sua sessão de navegador e assinando cada requisição do mesmo jeito que a página assina. Somente leitura: nenhuma operação de escrita na conta é implementada, e o escape hatch recusa APIs de escrita por construção.

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 (o cache usa bun:sqlite) e o Google Chrome para o login pela janela.

Tudo de uma vez (Claude Code)

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

setup compila o binário para ~/.local/bin/aliexpress, registra o servidor MCP aliexpress no escopo de usuário do seu ~/.claude.json e instala a Skill em ~/.claude/skills/aliexpress-mcp/.

npm

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

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

Binário único

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

O binário roda tudo, inclusive o login: o Playwright vai embutido e o Chrome vem do sistema.

Login

A senha nunca passa por aqui. Dois caminhos:

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

O primeiro abre uma janela do Chrome em aliexpress.com/p/order/index.html. Você digita a senha e resolve o que o AliExpress pedir (SMS, Google, captcha). A ferramenta fica perguntando à API, de dentro da própria página, se a sessão já vale, e só então grava os cookies.

O segundo é o mais rápido se você já usa o AliExpress 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.

Nos dois casos a sessão é gravada cifrada com AES-256-GCM em ~/.config/aliexpress-mcp/session.enc (0600). Detalhes, o que é gravado e como revogar: docs/LOGIN.md.

Uso — CLI

aliexpress status --verify        # a sessão ainda vale?
aliexpress sync                   # preenche o cache (repete os blocos sozinho)

aliexpress orders --limit 10
aliexpress orders --status shipped
aliexpress order 8212379857492017 --address
aliexpress search "cabo hdmi"
aliexpress track 8214565334582017
aliexpress refunds

aliexpress spending --by month --from 2026-01-01
aliexpress spending --by breakdown        # imposto, frete, cupons, parcelamento
aliexpress export --format csv --scope lines

aliexpress doctor                 # o que quebrou, camada a camada

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

Uso — MCP

O setup já registra o servidor. Manualmente:

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

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

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

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "quanto gastei no AliExpress este ano?", "onde está meu pedido da Baseus?", "quanto já paguei de imposto?".

Variáveis de ambiente

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

Sem sessão, os comandos falham na hora da chamada com uma mensagem que diz o que fazer, não no boot.

Tools

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

Como funciona

1. Login captura os cookies pelo Playwright, inclusive os HttpOnly, que document.cookie não enxerga e sem os quais nada autentica.

2. Cada chamada é assinada com md5(token & t & appKey & payload), o mesmo esquema do SDK do site. O token (_m_h5_tk) é de vida curta e o servidor o renova por Set-Cookie; o cliente absorve, reassina e repete.

3. A listagem e o detalhe vêm em Ultron/DX, um grafo de componentes. Os dados de negócio ficam em data["<tag>_<id>"].fields, e a ordem em que o usuário vê os pedidos está em hierarchy.structure, não na ordem das chaves do objeto.

4. Tudo é normalizado para um modelo limpo, com dinheiro em centavos inteiros, e guardado num SQLite local. As perguntas analíticas são respondidas dali, sem rede.

O que a API não tem: o número de parcelas (só a taxa). Está documentado em docs/DATA-MODEL.md para ninguém inventar esse número. Arquitetura em detalhe: docs/ARCHITECTURE.md.

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.