btgpactual-mcp

CLI + servidor MCP para a sua conta no BTG Pactual: saldo da conta corrente e do cheque especial, extrato, cartões, fatura com lançamentos e parcelas (titular e adicional separados), carteira de investimentos por classe e produto, extrato da conta investimento e o patrimônio que você conectou via Open Finance. Tudo vai para um cache local, então as perguntas são respondidas sem bater no banco a cada vez, e continuam respondidas depois que a sessão do banco expira.

O BTG não tem API para pessoa física consultar a própria conta. Este projeto usa o app web (app.btgpactual.com) por dentro de um Chrome autenticado: o canal de investimentos devolve JSON, e as telas do banco (que trafegam cifradas) são lidas já renderizadas, sem reimplementar a criptografia do app. Somente leitura: nenhuma operação que mexa na conta existe no código, o raw_get só aceita GETs no canal de investimentos, e o login (senha, "não sou robô", verificação em duas etapas) é sempre feito por você.

Sumário

• Instalação

• Login

• Uso — CLI

• Uso — MCP

• Variáveis de ambiente

• Tools

• Como funciona

• Troubleshooting

• Documentação

• Licença

Related MCP server: Banco do Brasil 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/btgpactual-mcp.git
cd btgpactual-mcp
bun install
bun run setup

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

npm

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

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

Binário único

bun run build:binary   # gera ./btgpactual
./btgpactual --version

O binário faz tudo, inclusive o login.

Login

btgpactual login

Abre uma janela dedicada do Google Chrome no app do BTG. Você faz o login normalmente (senha, "não sou robô", verificação em duas etapas), clica em Acessar na conta e espera a tela inicial. A ferramenta percebe sozinha, confere que a sessão funciona, guarda tudo cifrado e fecha a janela.

A janela é um Chrome comum, não controlado por automação, por isso o reCAPTCHA do banco aceita. A sessão fica em ~/.config/btgpactual-mcp/session.enc (AES-256-GCM, permissão 0600). Detalhes em docs/LOGIN.md.

Uso — CLI

btgpactual status                  # há sessão? de quando? (sem rede)
btgpactual sync                    # baixa tudo para o cache (precisa de sessão ativa)
btgpactual balance                 # conta corrente e conta investimento
btgpactual statement --direction out --from 2026-09-01
btgpactual cards                   # limites e gasto do titular e do adicional
btgpactual invoice                 # fatura da tela no último sync
btgpactual transactions --installments
btgpactual positions --class "renda fixa"
btgpactual spending --by merchant
btgpactual export --scope invoice_lines --format csv
btgpactual doctor                  # qual camada quebrou

Todo comando aceita --json. Referência completa em docs/CLI.md.

Uso — MCP

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

Ou direto no ~/.claude.json:

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

Use caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "qual meu saldo no BTG?", "o que está parcelado na fatura?", "quanto o cartão adicional gastou este mês?", "como está minha carteira de renda fixa?".

Variáveis de ambiente

Todas opcionais.

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

Tools

São 15, iguais no MCP e no CLI.

Parâmetros de cada uma em docs/TOOLS.md.

Como funciona

1. O login abre um Chrome comum para você entrar e copia a sessão da aba (sessionStorage, localStorage, cookies) pela porta de depuração local. A porta só fica aberta durante o login.

2. O app do BTG guarda a sessão no sessionStorage, que o Chrome não persiste entre execuções. Por isso o navegador de leitura (headless) restaura essa cópia antes de o app carregar, e o app acorda logado.

3. O canal de investimentos (/investments/api/) responde JSON. A ferramenta repete as chamadas de dentro da página, com os cabeçalhos de sessão que o próprio app emitiu.

4. O canal do banco (/banking/api/) é cifrado pelo app. Em vez de quebrar a cifra, a ferramenta abre as telas de cartões e da conta corrente e lê o HTML já desenhado. Na tela de cartões ela clica em cada mês do gráfico (com mouse de verdade) e só aceita a lista quando o próprio gráfico confirma o mês escolhido; no extrato, avança página por página até o fim.

5. Tudo vai para um SQLite local, com os valores em centavos inteiros e a resposta bruta guardada, para reprocessar sem rede quando um parser mudar.

Troubleshooting

Documentação

Licença

MIT. Projeto independente, sem relação com o BTG Pactual, para uso com a sua própria conta.