Bank Statement MCP

mcp-bank-statement

Servidor MCP para ler exportações CSV de extratos bancários, para ler, categorizar e conciliar transações. Exportações CSV de bancos categorizadas, resumidas e conciliadas com despesas.

Funciona com Claude Desktop, Claude Code, Cursor e qualquer cliente do Model Context Protocol. Roda na sua própria máquina ou hospedado, sem instalação.

Página do produto: https://mcp.zovo.one/s/bank-statement — o que faz, as ferramentas que expõe e um endpoint de token ao vivo.

Instalação

Hospedado, nada para instalar. Obtenha um token em https://mcp.zovo.one/mcp/connect (a página de conexão) ou https://mcp.zovo.one/mcp/token (o mesmo token como JSON); um token anônimo gratuito é emitido na hora e uma chave Pro funciona da mesma forma. Em seguida, aponte um cliente MCP para https://mcp.zovo.one/mcp/bank-statement via streamable-http e envie o token como Authorization: Bearer <token>.

Se o seu cliente não puder definir cabeçalhos, coloque o token no caminho: https://mcp.zovo.one/mcp/bank-statement/t/<token>. Ambas as formas funcionam. A URL simples sem token responde 401 em tools/call, então o token não é opcional.

Claude Desktop, um clique. Baixe bank-statement.mcpb do último lançamento e clique duas vezes nele.

A partir do código-fonte. O espelho é autossuficiente: toda dependência @theluckystrike/* é incluída, então um clone novo compila sem configuração extra.

git clone https://github.com/theluckystrike/mcp-bank-statement.git
cd mcp-bank-statement
npm install && npm run build

Em seguida, aponte seu cliente para o ponto de entrada compilado:

{
  "mcpServers": {
    "bank-statement": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bank-statement/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-bank-statement ainda não está publicado no npm, então um comando npx -y @theluckystrike/mcp-bank-statement falhará. Os três caminhos acima são os que funcionam e cada um é testado pela CI.

Espelho somente leitura de mcp-servers/servers/bank-statement. Veja MIRROR.md.

No Registro Oficial de MCP (io.github.theluckystrike/bank-statement-csv-categorize-reconcile-ledger).

Exporte o CSV do seu banco, diga "importe isso", e o mês fica legível. Este servidor MCP transforma uma exportação bancária em um livro-razão local: ele encontra a linha do cabeçalho sob qualquer preâmbulo que o banco imprima acima dela, descobre qual coluna é a data, qual é o valor e em que direção o dinheiro foi, e lê os valores no próprio locale do arquivo, então 1 234,56 do mBank e 1,234.56 de um banco dos EUA se tornam o mesmo número. Um débito é armazenado como negativo e um crédito como positivo, uma vez, na importação, para que nada a jusante precise adivinhar. Reimportar a mesma exportação não adiciona nada: cada linha carrega um hash de sua data, valor, moeda e descrição, com um índice de ocorrência, então dois cafés idênticos no mesmo dia continuam sendo duas transações, enquanto uma segunda importação do mesmo arquivo continua sendo zero. Suas regras categorizam as transações conforme elas chegam, os resumos relatam dinheiro entrando, dinheiro saindo e o líquido por moeda e nunca misturam moedas, recurring_detect encontra as assinaturas e quanto cada uma custa por ano, e reconcile_expenses combina débitos bancários com os recibos em mcp-expense-tracker para que você veja quais débitos não têm recibo e quais recibos nunca chegaram ao banco. Tudo é um arquivo JSON simples na sua própria máquina; nada é enviado para lugar nenhum.

Transforme um CSV bancário em um mês categorizado e conciliado no chat, sem precisar de SaaS de contabilidade.

Perfis de banco: Revolut, Wise, mBank, PKO BP, ING, N26 e um leitor genérico que funciona apenas com os cabeçalhos.

Formatos de arquivo que ele lê sem ser solicitado: UTF-8 e UTF-16 (em qualquer ordem de bytes, como o Excel no Windows salva), terminações de linha CRLF, LF e apenas CR, campos entre aspas contendo vírgulas, aspas e quebras de linha, 1.234,56 e 1,234.56, parênteses contábeis (12.50) e um sinal de menos no final 12.50- (ambos negativos), e uma mistura de moedas dentro de um único arquivo. Uma célula contendo - ou nada é ignorada e nomeada em skipped_lines em vez de ser lida como zero. Quando a coluna de data é ambígua (03/04/2026 sem valor acima de 12 em lugar nenhum), a ordem assumida é declarada na resposta em vez de escolher uma silenciosamente.

Instalação em 60 segundos

A publicação no npm para @theluckystrike/mcp-bank-statement está pendente. Até lá, o pacote de um clique .mcpb ou um clone+compilação são o caminho que funciona, ambos verificados abaixo.

Um clique (.mcpb): baixe bank-statement.mcpb do último lançamento e clique duas vezes nele no Claude Desktop: https://github.com/theluckystrike/mcp-servers/releases/latest

(claude_desktop_config.json):

{
  "mcpServers": {
    "bank-statement": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-bank-statement"]
    }
  }
}

Claude Code:

claude mcp add bank-statement -- npx -y @theluckystrike/mcp-bank-statement

(.cursor/mcp.json):

{
  "mcpServers": {
    "bank-statement": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-bank-statement"]
    }
  }
}

O formato npx acima começa a funcionar no momento em que o pacote é publicado. Até lá, use o pacote .mcpb acima, ou compile a partir do código-fonte com exatamente estes três comandos:

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/spreadsheet -w servers/bank-statement

Em seguida, aponte o command do seu cliente para node com um argumento: o caminho absoluto para servers/bank-statement/dist/index.js.

Para rodar em modo Pro, defina MCP_LICENSE_KEY no mesmo bloco de configuração, ou chame license_activate uma vez com sua chave.

Ferramentas

Ferramenta	O que faz
statement_import	Lê um CSV bancário para o livro-razão. Detecta a linha do cabeçalho sob qualquer preâmbulo, as colunas de data, descrição, valor (ou débito e crédito) e moeda, a ordem da data e o locale numérico. Relata o que detectou, o que armazenou, quantas linhas eram duplicatas do que já existe e cada linha ignorada com o motivo
transactions_list	Lista transações em um intervalo de datas, filtradas por conta, categoria ou uncategorized, com totais por moeda
transactions_search	Encontra transações cuja descrição, contraparte, categoria ou conta contém a consulta. Somente substring, nunca regex
category_rules	Define ou lista as regras que categorizam transações. Uma correspondência vazia é recusada, porque carimbaria uma categoria em todo o livro-razão. Uma correspondência simples é uma substring sem diferenciar maiúsculas de minúsculas; regex: true compila o padrão somente se ele não puder fazer retrocesso exponencial, e (a+)+ é recusado e usado como substring. Definir regras as reaplica às transações armazenadas
transaction_categorize	Define a categoria das transações por id. Nada muda a menos que todos os ids existam
statement_summary	Dinheiro entrando, dinheiro saindo e o líquido para um intervalo, agrupado por categoria, mês, conta ou contraparte, sempre por moeda
reconcile_expenses	Combina débitos bancários com os recibos em mcp-expense-tracker: mesma moeda, mesmo valor, dentro de uma janela de datas. Relata correspondências, linhas bancárias sem recibo e recibos que nunca chegaram ao banco. O livro-razão de despesas é apenas lido
recurring_detect	Encontra assinaturas e cobranças recorrentes: a mesma contraparte, um valor que mal muda, um ritmo constante. Relata o ritmo, o valor típico, a próxima data esperada e o custo anualizado. Duas cobranças são um intervalo, então o custo anual é retido (cadence_confirmed: false) até que uma terceira cobrança o confirme
statement_export	Escreve um intervalo em csv ou json e retorna o caminho. Escrito atomicamente, então uma falha nunca deixa um arquivo pela metade. Substituir um arquivo existente é permitido e relatado (overwrote_existing_file)
accounts_list	As contas importadas, com banco, moedas, contagem de transações, intervalo de datas e último saldo
license_status	Mostra o modo gratuito ou Pro
license_activate	Ativa uma chave Pro (verificada offline)

O recurso bank://month retorna o dinheiro entrando, saindo e o líquido deste mês, agrupado por categoria, por moeda. O prompt monthly_review conduz todo o processo de fechamento do mês: totais, linhas não categorizadas, assinaturas, reconciliação.

Gratuito vs Pro

	Gratuito	Pro
Contas	2	ilimitadas
Leitura do histórico	últimos 12 meses	tudo
Regras de categoria	5	ilimitadas
Importar, listar, buscar, resumir	sim	sim
reconcile_expenses	sim, 31 dias por vez	qualquer intervalo de datas
recurring_detect	sim, últimos 3 meses, 5 cobranças	histórico completo, todas as cobranças
statement_export	não	sim

A importação sempre armazena todas as linhas, independentemente do nível: descartar linhas silenciosamente na entrada faria o livro-razão discordar do banco. O limite gratuito é sobre o que é lido de volta.

Obtenha o Pro: https://mcp.zovo.one/buy/bank-statement, US$ 19 pagamento único para este servidor, US$ 39 para todos os servidores, vitalício. As chaves são verificadas offline; nada é enviado para lugar nenhum.

Combina com

• mcp-expense-tracker, registre os recibos e a quilometragem; reconcile_expenses lê esse livro-razão e informa quais débitos bancários não têm recibo por trás.
• mcp-spreadsheet, este servidor analisa seu CSV bancário com o leitor RFC 4180 do próprio servidor de planilhas e o analisador numérico de locale, então 1 234,56 significa a mesma coisa em ambos. Use-o para fatiar um intervalo exportado.
• mcp-invoice, o lado da receita: emita a fatura e depois veja o pagamento chegar em statement_summary agrupado por contraparte.

Privacidade

Tudo permanece na sua máquina. Os extratos são analisados localmente e armazenados em um arquivo JSON simples em ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/bank-statement/. O servidor não faz nenhuma chamada de rede, nem para licenciamento, nem para análise, nem para nada. Excluir esse diretório redefine tudo.

Construído por theluckystrike. Suporte: support@zovo.one

Use estes documentos como um servidor MCP

Qualquer cliente MCP (Claude, Cursor, Windsurf, VS Code) pode ler a documentação deste repositório diretamente via GitMCP — sem instalação:

• URL MCP dos documentos: https://gitmcp.io/theluckystrike/mcp-bank-statement