btgpactual
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
Related MCP server: Inter 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 setupsetup 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 --versionO pacote roda com o Bun (bun:sqlite), então o Bun precisa estar instalado.
Binário único
bun run build:binary # gera ./btgpactual
./btgpactual --versionO binário faz tudo, inclusive o login.
Login
btgpactual loginAbre 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 quebrouTodo comando aceita --json. Referência completa em docs/CLI.md.
Uso — MCP
claude mcp add -s user btgpactual -- /Users/voce/.local/bin/btgpactual mcpOu 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.
Variável | Default | Para quê |
|
| Sessão, cache e perfis do Chrome |
|
| Chave da sessão cifrada (base64 de 32 bytes) |
|
| Único diretório onde |
|
|
|
| descoberta sozinha | Número da conta de investimento |
|
|
|
| Chrome do sistema | Executável usado pelo |
A tabela completa está em docs/CONFIGURATION.md.
Tools
São 15, iguais no MCP e no CLI.
Tool | Comando | Rede |
|
| não (1 requisição com |
|
| abre o Chrome |
|
| não (1 requisição + 1 tela com |
|
| ~5 requisições + 2 telas e cliques (~1,5 min) |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| não |
|
| 1 requisição |
Parâmetros de cada uma em docs/TOOLS.md.
Como funciona
O
loginabre 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.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.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.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. As faturas que o gráfico já não mostra vêm da página "Fatura completa": a ferramenta abre a da fatura fechada pelo link do app, pergunta ao seletor desde quando existem faturas e lê cada mês que falta, conferindo o mês no título de cada página. No extrato, avança página por página até o fim.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
Sintoma | O que fazer |
"Nenhuma sessão salva" ou "pediu login" |
|
"Nada sincronizado ainda" |
|
O login não passa do "não sou robô" | Use o |
"A sessão salva para na seleção de conta" | Rode |
Uma etapa do |
|
Uma tela parou de ser lida depois de um deploy do BTG | |
"O BTG exigiu verificação adicional" | Pare, abra o app no navegador, resolva e espere o tempo indicado |
Documentação
Arquivo | Conteúdo |
Do zero à primeira resposta | |
Todos os comandos e opções | |
Todas as tools e parâmetros (gerado) | |
Variáveis, arquivos, registro no Claude Code | |
Como a sessão é obtida, guardada e revogada | |
Camadas, fluxo de uma pergunta, regras | |
O que cada número significa, o cache, o que não existe | |
Os dois canais do app e as telas lidas | |
O que fazer quando o BTG mudar | |
Decisões de arquitetura (13) |
Licença
MIT. Projeto independente, sem relação com o BTG Pactual, para uso com a sua própria conta.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial, not affiliated with BTG Pactual. Read-only Open Finance MCP by MCP.AI.
Ask your AI about Brazilian bank spending. Read-only bank access, never moves money. Paid plan.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Chat with your bank data: balances, transactions, budgets, bills. Reads only, never moves money.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConecta sua conta BTGPactual a assistentes de IA via Open Finance Brasil, permitindo consultas de saldos, extratos, faturas de cartão e investimentos em linguagem natural (somente leitura).MIT
- AlicenseNot gradedqualityCmaintenanceConnects your Inter bank account to AI assistants via Open Finance Brasil, enabling read-only queries about balances, statements, credit card bills, and investments in natural language.MIT
- AlicenseNot gradedqualityCmaintenanceEnables natural language queries to read balances, statements, credit card bills, investments, and loans from Next bank accounts via Open Finance Brasil. All read-only, no money movement.MIT
- AlicenseNot gradedqualityCmaintenanceConnects your Ágora bank account via Open Finance Brasil to AI agents like Claude and ChatGPT, enabling natural language queries about balances, statements, credit card bills, and investments in read-only mode.MIT