shein-mcp

CLI + servidor MCP para o histórico de compras da sua conta na Shein: pedidos, itens, o breakdown que soma o total (produtos, frete, imposto, taxa de parcelamento, seguros), rastreio, devoluções e resumos de gastos, com cache local, para você perguntar quanto gastou sem bater na Shein a cada pergunta.

A Shein não tem API de comprador. O portal de desenvolvedores dela é para vendedores e não dá acesso ao histórico da sua própria conta. Este projeto fala a mesma API interna que o site usa (/bff-api/order/* em br.shein.com), autenticado pelos cookies da sua sessão de navegador. Somente leitura: nenhuma operação de escrita na conta é implementada, e o escape hatch recusa paths 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 (o login e o transporte de reserva abrem um Chrome de verdade).

Tudo de uma vez (Claude Code)

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

setup compila o binário para ~/.local/bin/shein, registra o servidor MCP shein no seu ~/.claude.json (escopo de usuário) e instala a skill em ~/.claude/skills/shein-mcp/. Rode de novo para atualizar.

npm

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

O pacote roda com o Bun (#!/usr/bin/env bun, por causa do bun:sqlite), então o Bun precisa estar instalado.

Binário único

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

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

Login

A senha nunca passa por aqui. Dois caminhos:

shein login                        # abre o Google Chrome para você entrar
shein 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 Shein 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/shein-mcp/session.enc (0600). Detalhes em docs/LOGIN.md.

Uso — CLI

shein status --verify                # a Shein ainda aceita a sessão?
shein sync                           # baixa o histórico para o cache local
shein orders --limit 10              # seus pedidos, do mais novo para o mais antigo
shein order GSH…                     # um pedido inteiro, com o breakdown de preço
shein track GSH…                     # rastreio ao vivo
shein search "conjunto"              # entre os produtos que você já comprou
shein products --limit 20            # agregado por produto
shein product-history "camisola"     # cada compra do produto e a evolução do preço
shein spending --by month            # quanto você gastou por mês
shein spending --by breakdown        # quanto foi produto, frete, imposto, parcelamento
shein export --format csv            # para planilha
shein 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

O setup já registra o servidor. À mão, no Claude Code:

claude mcp add -s user shein -- /Users/voce/.local/bin/shein mcp

Ou direto em ~/.claude.json:

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

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "quanto gastei na Shein este ano?", "onde está meu último pedido?", "já comprei essa camisola antes?".

Variáveis de ambiente

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

Tools

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

Como funciona

O site serve o histórico por duas superfícies: páginas SSR que trazem um bloco var gbRawData = {…} e uma API JSON interna (/bff-api/order/*) que responde só com os cookies da sessão. O sync percorre a listagem em blocos, guarda o payload cru de cada pedido e normaliza tudo para um modelo com dinheiro em centavos inteiros; as perguntas depois disso são SQL local.

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

• total é a soma das linhas de sorted_price com show: "1", verificado em 21 de 21 pedidos. Os campos com nome (subTotalPrice e afins) são rótulos da Shein e não formam uma equação.

• O rastreio mora em packageMap, não em trackInfo: em 8 de 21 páginas o segundo simplesmente não existe.

• A situação do pedido é lida pelos sinais (pagou? expirou? o pacote foi assinado?), não pelo código da Shein. O rótulo dela é a última coisa que aconteceu, não o estado de agora.

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.

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.