Model Context Protocol
Fale com seu razão a partir das ferramentas de IA que você já usa
O servidor MCP Beancount conecta seu razão em texto puro ao Claude Code, Claude Desktop, Cursor, Windsurf, Zed — qualquer cliente de IA compatível com MCP. Sem copiar e colar. Sem exportações. Basta perguntar.
URL do servidor MCP
https://beancount.io/api-gateway/mcp> Qual é o meu patrimônio líquido hoje?
⏺ runBqlQuery("SELECT sum(position) WHERE account ~ 'Assets|Liabilities'")
Seu patrimônio líquido hoje é 128,450.32 USD.
> Adicione o jantar da equipe de ontem, 42 USD, e confirme-o
⏺ editLedgerFiles(dry_run: true) → +1 transaction
⏺ git commit a1b4f2e — "AI edit: add team dinner transaction"
Concluído — confirmado no seu razão com trilha de auditoria completa.
Basta perguntar
Responder "quanto gastei em viagens no último trimestre?" costumava significar saber a sintaxe BQL, encontrar os arquivos certos e copiar os resultados para um chat. Agora é uma frase.
“Qual é o meu patrimônio líquido hoje?”
Uma resposta ao vivo extraída do seu razão real — não um palpite.
“Resuma as despesas do mês passado”
A IA escreve a consulta BQL para você e lê os resultados em voz alta.
“Adicione uma transação e confirme-a no git”
Uma confirmação real no repositório do seu razão, reversível como qualquer outra.
“O que há no meu repositório do razão?”
Navegue e leia seus arquivos .beancount sem sair do seu editor.
O que a IA pode fazer
O servidor expõe quatro ferramentas de razão. A IA as compõe: descubra sua estrutura de arquivos, leia para contexto, consulte para respostas, proponha uma edição.
runBqlQuery
Execute consultas BQL (Beancount Query Language) contra saldos, transações e contas.
listLedgerFiles
Navegue pela estrutura de diretórios do seu repositório de ledger.
readLedgerFiles
Leia o conteúdo dos seus arquivos .beancount e outros documentos do ledger.
editLedgerFiles
Crie, atualize, substitua ou exclua arquivos em um commit git atômico.
Conecte-se em menos de um minuto
Escolha seu cliente de IA. Copie. Cole. Pergunte.
- Execute este comando no seu terminal.
- O Claude Code abrirá uma janela do navegador — faça login e escolha qual ledger conectar.
- Aprove uma vez. As credenciais são renovadas automaticamente a partir daqui.
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpTem mais de um ledger? Adicione o servidor novamente com um nome diferente e autorize o outro ledger no próprio prompt:
claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcpNão tem uma conta Web Beancount? Cadastre-se em beancount.io — seu ledger está a um git push de distância.
Seu ledger, protegido
Uma IA com acesso de escrita aos seus livros ganha confiança pelo design, não por promessas.
OAuth 2.1 com escopo de ledger
Uma sessão é autorizada para exatamente um ledger. Uma sessão para seu ledger pessoal não pode tocar seu ledger comercial — raio de explosão, limitado.
Cada edição é um commit git
As alterações são registradas como commits reais ("AI edit: …") no repositório do seu ledger — um rastro de auditoria completo que você pode revisar e reverter com ferramentas git padrão.
Pré-visualizações em modo de teste
editLedgerFiles suporta um modo dry_run que valida e pré-visualiza as alterações exatas sem escrever nada, para que seu cliente possa mostrar um diff antes.
Servidor sem estado
O servidor MCP não armazena nada além do que a conversa do seu cliente de IA já contém. Seu ledger permanece onde está hoje.
Seu ledger inteiro já é um repositório git. Veja como o Git for Beancount funciona
Perguntas frequentes
O que é MCP e por que isso importa para o Beancount?
MCP (Model Context Protocol) é um padrão aberto que permite que assistentes de IA chamem ferramentas e fontes de dados externas de forma estruturada e segura. Em vez de adivinhar ou pedir que você cole dados, seu cliente de IA se conecta diretamente ao seu ledger — ele consulta seus dados reais, lê seus arquivos reais e faz edições precisas.
Quais clientes de IA funcionam com o servidor MCP do Beancount?
Qualquer cliente compatível com MCP que suporte OAuth 2.1 funciona imediatamente, incluindo Claude Code, Claude Desktop, Cursor, Windsurf e Zed. Clientes sem suporte a OAuth 2.1 podem se conectar com um token estático gerado nas configurações da sua conta beancount.io.
Como conecto meu ledger?
Adicione a URL do servidor à configuração MCP do seu cliente. No primeiro uso, o cliente abre uma janela do navegador — faça login com sua conta Web Beancount e escolha o ledger ao qual deseja conceder acesso. O cliente armazena e atualiza as credenciais automaticamente a partir daí.
O que a IA pode realmente fazer com meu ledger?
O servidor expõe quatro ferramentas: runBqlQuery executa consultas Beancount Query Language, listLedgerFiles navega pelo repositório do seu ledger, readLedgerFiles lê seus documentos contábeis e editLedgerFiles cria, atualiza ou exclui arquivos em um commit git atômico. A IA as combina para responder perguntas e propor edições.
A IA pode modificar meu ledger sem eu saber?
As edições passam pela ferramenta editLedgerFiles, que clientes MCP bem-comportados exibem para você antes de executar. Um modo dry_run pré-visualiza as alterações exatas sem escrever nada, e cada alteração cometida é um commit git real — um rastro de auditoria completo que você pode reverter com ferramentas git padrão.
Meus dados são enviados a terceiros?
Seus dados do ledger fluem pelo backend Web Beancount, que já gerencia seu ledger, e retornam como resultados estruturados para seu cliente de IA. As sessões são limitadas ao ledger: cada uma pode acessar exatamente o ledger que você autorizou, e o servidor MCP não armazena nada além do que a conversa do seu cliente de IA contém.
Curioso sobre como é construído? Leia o FAQ de engenharia no blog
Seus dados contábeis encontram seu fluxo de trabalho de IA
O servidor MCP do Beancount está disponível hoje para todos os usuários do Web Beancount. Seu ledger está a um git push de distância.