Statement of Account MCP

mcp-statement-of-account

Servidor MCP para extratos de conta de clientes, contas a receber e aging de faturas. O documento único que responde o que um cliente realmente te deve, com aging em qualquer data, e com o cobrador já redigido.

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

Página do produto: https://mcp.zovo.one/s/statement-of-account — 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/statement-of-account 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/statement-of-account/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 statement-of-account.mcpb da última versão e clique duas vezes nele.

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

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

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

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

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

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

No Registro Oficial MCP (io.github.theluckystrike/statement-of-account). Envie ao cliente o único documento que responde "o que eu realmente te devo". Este servidor MCP lê os livros que você já mantém neste conjunto, suas faturas, suas notas de crédito e seus depósitos, e os transforma em um extrato de conta para um período: o saldo que você carregava no início, cada fatura emitida, cada pagamento recebido, cada nota de crédito concedida e o saldo no final. Ele faz o aging do que ainda está aberto em 0-30, 31-60, 61-90 e mais de 90 dias em atraso, para que você veja rapidamente qual cliente é o problema; ele escreve o extrato como texto colável ou como PDF A4 que se parece com suas faturas; e redige o cobrador, em nível amigável, firme ou final. Ele nunca escreve nada de volta em suas faturas e nunca inventa uma taxa de atraso.

Construído por theluckystrike.

A publicação no npm para @theluckystrike/mcp-statement-of-account está pendente, então npx -y @theluckystrike/mcp-statement-of-account retorna 404 hoje. Até lá, o pacote de um clique .mcpb ou um clone+compilação é o caminho que funciona.

Instalação

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

claude mcp add statement-of-account -- npx -y @theluckystrike/mcp-statement-of-account

Cursor

~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto), mesma entrada do Claude Desktop.

Ferramentas

ferramenta	o que faz
statement_build	Extrato de um cliente para um período: saldo inicial, faturas emitidas, pagamentos recebidos, notas de crédito, depósitos aplicados, saldo final. Todos os valores em unidades menores e formatados
statement_aging	O que é devido, dividido em 0-30, 31-60, 61-90 e mais de 90 dias após o vencimento em uma data escolhida, para um cliente ou para todos, por moeda
statement_text	O mesmo extrato como texto simples, movimentações em ordem de data, pronto para colar em um e-mail
statement_pdf	O mesmo extrato como PDF A4 intitulado STATEMENT OF ACCOUNT, no mesmo layout de página de suas faturas e notas de crédito
dunning_text	Um cobrador de pagamento no nível 1 (amigável), 2 (firme) ou 3 (cobrança final), com a lista de vencidos e seus dados bancários
statements_report	Todos os clientes de uma vez: o que está pendente por moeda, com aging, e a fatura vencida mais antiga do livro
license_status	Gratuito ou Pro, e onde atualizar
license_activate	Ativar uma chave Pro

Além do recurso statement://sources, que informa quais dos três armazenamentos este servidor poderia ler e quantas linhas cada um contém, e o prompt chase_overdue.

Gratuito vs Pro

	Gratuito	Pro
Extratos construídos	5 por mês calendário	ilimitado
Reconstruir um extrato já construído	ilimitado	ilimitado
statement_aging	ilimitado	ilimitado
statement_text	sim	sim
dunning_text níveis 1 e 2	sim	sim
dunning_text nível 3, cobrança final	não	sim
statement_pdf	não	sim
statements_report	não	sim
Crédito no rodapé do PDF	exibido	removido

O aging é gratuito e ilimitado de propósito. "Quem me deve dinheiro" é a pergunta para a qual todo este servidor existe, e um nível gratuito que a esconde é uma demonstração, não uma ferramenta. O medidor está no extrato, o documento que realmente vai para o cliente, e conta extratos distintos: o mesmo cliente, período e moeda reconstruídos é gratuito para sempre.

Obtenha o Pro, pagamento único, vitalício, para este servidor. As chaves verificam offline.

De onde vêm os números

Nada aqui é digitado duas vezes. O servidor lê três armazenamentos e não escreve em nenhum deles:

armazenamento	servidor	o que é retirado dele
invoices.json	mcp-invoice	as faturas, suas datas de vencimento e quanto de cada uma está pago
credit-notes.json	mcp-billing-docs	as notas de crédito, já armazenadas com sinal negativo
deposits.json	mcp-deposits	as aplicações de depósito e o que ainda está retido

Um armazenamento que você nunca instalou simplesmente está ausente, e o extrato é construído sem ele. Um armazenamento que está no disco e não pode ser LIDO é algo completamente diferente e é relatado como tal em cada valor, porque um saldo que não pôde ser calculado nunca deve ser exibido como um saldo de nada devido. O único armazenamento sem o qual o servidor se recusa a trabalhar é o livro de faturas.

Uma percepção medida

Fazer aging de uma data passada com os valores de pagamento de hoje não é levemente errado, é silenciosamente vazio. O aging geralmente é escrito como "pegue cada fatura, subtraia o que foi pago e agrupe pela data de vencimento". A subtração é a parte que ninguém data. No mês trabalhado em test/_client.mjs, com aging em 2026-06-10, as duas regras dão:

regra	pendente	vencido
em 2026-06-10	2.500,00 EUR	500,00 EUR, 31 dias em atraso
paid_minor de hoje	1.700,00 EUR	0,00 EUR

A regra ingênua subestima o que era devido em 800,00 de 2.500,00, um terço do saldo, e relata NADA vencido em uma data em que uma fatura estava um mês atrasada, porque um pagamento que chegou dois dias depois já foi subtraído dela. A falha é invisível: a resposta parece organizada, os intervalos somam corretamente e não pode ser reproduzida no próximo mês porque a entrada continua mudando. Portanto, cada valor em statement_aging é considerado na data solicitada, em ambas as direções: uma fatura emitida depois não está nos livros, um pagamento feito depois não aconteceu e uma nota de crédito emitida depois não foi concedida.

A segunda coisa que a medição mostrou: paid_minor e payments[] em uma fatura não precisam concordar e rotineiramente não concordam. invoice_mark_paid escreve ambos, mas deposit_apply levanta paid_minor e não anexa nenhuma linha de pagamento, e uma fatura criada antes de esse campo existir também não tem linhas. Reconstruir recebimentos de payments[] teria perdido 300,00 dos 900,00 de recebimentos do mês trabalhado, um terço do dinheiro, sem erro em lugar nenhum. paid_minor é tratado como a autoridade e as linhas são apenas a atribuição.

Regras que este servidor mantém

• Um depósito é dinheiro que se move uma vez. Aplicar um depósito já escreve o pagamento na fatura, então o extrato o conta lá e o detalha como "dos quais depósitos aplicados" em vez de creditá-lo uma segunda vez. O dinheiro de depósito ainda retido é uma linha de memorando e nunca faz parte do saldo: é o dinheiro do cliente até ser aplicado.
• Moedas nunca são somadas. Um extrato é uma moeda, e um cliente cobrado em duas é questionado sobre qual. Não há taxa de câmbio neste servidor, então um único valor em um livro em EUR e um em USD seria um valor inventado.
• Vencido hoje não é atrasado. Uma fatura entra no intervalo 0-30 no primeiro dia após sua data de vencimento. O que está pendente mas ainda não venceu é relatado ao lado dos intervalos, nunca dentro deles e nunca oculto.
• Uma nota de crédito reduz a fatura que nomeia e nenhuma outra. Um saldo aberto tem piso em zero e qualquer excesso é relatado como crédito não aplicado, em vez de cancelar silenciosamente uma fatura contra a qual o cliente nunca concordou.
• Nenhum cobrador inventa uma cobrança. Os três níveis de cobrança diferem em tom e prazo e em nada mais. Nenhum nível declara uma taxa de atraso, uma taxa de juros ou um custo legal, porque este servidor não contém termos contratuais, taxa estatutária ou jurisdição, e o único lugar onde nunca se deve colocar um número inventado é em uma cobrança de dinheiro.
• Um cobrador para um cliente sem nada vencido é recusado, e a recusa informa o que está pendente mas ainda não venceu.

Privacidade

Todos os dados permanecem na sua máquina. As faturas, notas de crédito e depósitos são lidos de ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/, o registro próprio deste servidor de extratos construídos é escrito em .../mcp-servers/statement-of-account/, e nada é enviado para lugar nenhum. Não há chamada de rede neste servidor. As chaves de licença verificam offline.

Licença

MIT. Suporte: support@zovo.one

Construído por theluckystrike.

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 do MCP de Documentação: https://gitmcp.io/theluckystrike/mcp-statement-of-account