MainBook Bank Statement Converter

Converta extratos bancários em PDF para Excel, CSV ou JSON verificados com validação de saldo.

Ver em mainbook.ai

Documentação

MCP · Claude, Claude Code, Cursor, Codex

Servidor MCP de Extratos Bancários

Um servidor MCP financeiro focado em uma única tarefa: transformar extratos bancários em PDF em JSON, Excel ou CSV verificados — não é um MCP contábil geral. Ele roda localmente com sua chave de API MainBook.

Crie uma chave de API mainbook-mcp no PyPI →

~/Downloads — claude

Converta ~/Downloads/march-statement.pdf e salve o Excel ao lado dele.

mainbook - convert_bank_statement (MCP)(path: "~/Downloads/march-statement.pdf", output: "xlsx")

63 transações · 4 páginas · 4 créditos

Totais conciliados com o extrato

Salvo em ~/Downloads/march-statement.xlsx

+2 linhas (ctrl+o para expandir)

Pronto — 63 transações. Saldo inicial de 4.127,50 e saldo final de 3.881,05 ambos batem com o extrato, e nada foi sinalizado.

Configuração local via stdio

Adicione ao seu cliente

Escolha a configuração do cliente, substitua o espaço reservado da chave e nomeie apenas as pastas que o servidor pode usar.

Configuração do cliente verificada em 14 de agosto de 2026

MainBook MCP · configuração do cliente

Claude Desktop · Claude Code · Cursor · JSON

{
  "mcpServers": {
    "mainbook": {
      "command": "uvx",
      "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"],
      "env": { "MAINBOOK_API_KEY": "mb_live_…" }
    }
  }
}

Codex · TOML

[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

[mcp_servers.mainbook.env]
MAINBOOK_API_KEY = "mb_live_…"

Instale o pacote local

Instale o uv, que inclui uvx

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Ou instale e atualize com pip

pip install mainbook-mcp

pip install -U mainbook-mcp

  • Locais do cliente Claude Desktop: Configurações → Desenvolvedor → Editar Config. O mesmo JSON funciona no Claude Code e no Cursor.
  • Limite de pastas Passe as pastas em args, ou defina MAINBOOK_ALLOWED_DIRS. Nessa variável de ambiente, separe os caminhos com dois-pontos (:) no macOS/Linux e ponto e vírgula (;) no Windows.
  • Runtime Python 3.11+; uvx busca o pacote sem ampliar o limite de pastas.
  • Fallback com pip Use mainbook-mcp como comando após instalar com pip; atualize o pacote com -U.

Ferramentas e solicitações

Cinco ferramentas, quatro solicitações úteis

A paleta mostra a capacidade exata; a transcrição abaixo mostra como uma pessoa solicita.

mainbook · cinco ferramentas e exemplos de solicitações

Paleta de ferramentas

5 ações explícitas · sem mutação de conta

  • convert_bank_statement
    Faz upload de um PDF, cria e inicia um job de conversão, faz polling por até 30–900 segundos e retorna JSON revisado inline ou grava XLSX/CSV no disco.
    Consome créditos de página
  • get_conversion
    Verifica um job após um timeout, retornando JSON inline ou gravando XLSX/CSV em um destino local escolhido.
    Sem créditos · pode gravar um arquivo
  • list_conversions
    Retorna uma página de cursor dos jobs da conta junto com o valor next_cursor.
    Acesso somente leitura à conta
  • get_balance
    Retorna créditos total, reservado e disponível, todos medidos em páginas de PDF.
    Acesso somente leitura à conta
  • output_folder
    Lê ou altera a pasta local padrão onde os resultados da conversão são gravados.
    Sem créditos · preferência local

convert_bank_statement sozinho cria um job e consome créditos de página. Nenhuma ferramenta compra créditos, processa pagamentos, exclui jobs ou altera dados da conta.

Pergunte em linguagem natural

Cada solicitação abaixo resolve para uma ferramenta

  • Converta ~/Downloads/march-statement.pdf e salve o Excel ao lado dele.
    usaconvert_bank_statement
  • Quantas páginas de crédito ainda tenho?
    usaget_balance
  • A última conversão expirou — verifique o job 8f14e45f… e me entregue o CSV.
    usaget_conversion
  • Liste minhas conversões recentes e me diga quais voltaram com avisos.
    usalist_conversions

Roteamento local de resultados

Onde seus arquivos vão parar

O primeiro destino disponível vence. O servidor nunca substitui um arquivo que já existe.

MainBook · roteamento local de resultados

Prioridade 1output_path

Nome de arquivo absoluto ou pasta existente

Prioridade 2output_folder

Pasta local lembrada

Prioridade 3source folder

Mesmo nome base + extensão solicitada, ao lado do PDF

~/Downloadspasta permitida

march-statement.pdf

origem

march-statement.xlsx

salvo ao lado do PDF

march-statement (2).xlsx

nunca sobrescrito

depois (3), e assim por diante

JSON

inline, a menos que output_path esteja definido

get_conversion precisa de uma pasta explícita ou lembrada; ele nunca adivinha o local do PDF original.

Lembrado em ~/.mainbook/preferences.json e compartilhado por clientes locais; uma pasta ausente ou não permitida é ignorada e o fallback é reportado.

Limite local · créditos compartilhados · trabalho assíncrono

Limites, créditos e tempo

Uma visão operacional cobre o que o servidor pode acessar, o que uma conversão consome, quanto tempo o cliente espera e o contrato público por baixo.

mainbook-mcp · limite local e API pública

Chave de API da conta

Mantenha-a privada e revogue-a no aplicativo se for exposta. O servidor pode usar a conta, mas não tem ferramenta de pagamento ou exclusão.

Apenas pastas nomeadas

As pastas listadas são legíveis e graváveis. Qualquer coisa fora delas é recusada pelo servidor stdio local.

1 página = 1 crédito

Reservado para cada página do PDF.

20 páginas

Bônus de cadastro de nova conta, não um tier MCP separado.

Carteira compartilhada

Os pacotes são comprados no aplicativo web. O servidor MCP não pode comprar créditos.

Janela de polling

30s mínimo900s teto

Nenhuma duração média é publicada. Se o cliente expirar, o job do servidor continua; chame get_conversioncom o ID do job ou aumente o timeout de ferramenta do cliente.

Limites operacionais

500 páginas

máximo por PDF

50 MB

máximo por PDF

6 jobs

em andamento por chave de API

90 dias

retenção de documento + resultado

Abaixo do servidor local está a API REST pública. Use-a diretamente ao construir sua própria integração em vez de dirigir um assistente.

Guia da API RESTOpenAPI JSONSwagger UI

Leia a visão geral de tratamento em Segurança. A conta deve aceitar os Termos da API; caso contrário, as chamadas falham com api_terms_not_accepted. As divulgações de dados aplicáveis estão na Política de Privacidade e na Divulgação de IA.

As perguntas comuns

Perguntas frequentes

Com quais clientes MCP isso funciona?

Funciona com Claude Desktop, Claude Code, Cursor e Codex usando os blocos de configuração acima.

Preciso instalar algo?

O uv/uvx busca e executa o pacote mainbook-mcp publicado, ou você pode executar pip install mainbook-mcp. Python 3.11 ou mais recente é necessário.

O agente pode ler todo o meu disco?

Não. Ele só pode ler ou gravar dentro das pastas passadas como argumentos ou definidas via MAINBOOK_ALLOWED_DIRS; qualquer coisa fora delas é recusada.

O agente pode gastar meu dinheiro?

convert_bank_statement consome créditos de página da sua conta; não há ferramenta para comprar créditos, pagamentos ou excluir nada.

O que acontece se meu cliente desistir de esperar?

O job continua rodando no lado do servidor; chame get_conversion com o ID do job para retomá-lo.

Existe um servidor hospedado para o qual posso apontar?

O servidor roda localmente na sua máquina via stdio e fala com api.mainbook.ai a partir daí.

Dê ao seu assistente uma ferramenta útil

Crie a chave, nomeie as pastas e deixe o servidor local cuidar do fluxo de conversão.

Crie uma chave de API mainbook-mcp no PyPI →Leia o guia da API REST →