runBqlQuery
Execute consultas BQL (Beancount Query Language) contra saldos, transações e contas.
Model Context Protocol
Seu livro-razão entra na conversa.
Conecte o Beancount às ferramentas de IA que você já usa. Pergunte sobre suas finanças, trabalhe com seus arquivos de livro-razão e mantenha as alterações rastreáveis no Git.
Basta perguntar
Comece com uma pergunta. Siga a resposta de volta ao seu livro-razão.
Por trás da resposta
runBqlQuerySELECT sum(position) WHERE account ~ 'Assets|Liabilities'Beancount
Funciona com seu cliente compatível com MCP
- Claude Code
- Claude Desktop
- Cursor
- Windsurf
- Zed
Conecte o cliente que você já usa
Escolha seu cliente, adicione o servidor e autorize um livro-razão.
Claude Code
Execute este comando no seu terminal.
Abra o Claude Code e execute /mcp para autenticar. Entre no Web Beancount e escolha seu livro-razão.
Aprove uma vez. As credenciais são renovadas automaticamente a partir daqui.
Terminal
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/mcpUse sua conta Web Beancount para autorizar o acesso a um único livro-razão.
Não tem uma conta Web Beancount? Cadastre-se em beancount.io — seu ledger está a um git push de distância.
O que a IA pode fazer
O servidor expõe ferramentas especializadas para seu ledger, suas chaves de API e suas conexões bancárias — os verbos do ledger são mostrados abaixo. A IA os compõe: descubra sua estrutura de arquivos, lea para contexto, consulte para respostas, proponga uma edição.
Ledger, chaves de API e ferramentas bancárias. Seu cliente decide como usá-las.
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.
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.
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.
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.
Servidor sem estado
O servidor MCP não mantém estado de sessão entre chamadas de ferramentas. Seu cliente de IA e modelo escolhidos recebem os resultados solicitados; verifique as políticas de dados deles antes de conectar.
Seu ledger inteiro já é um repositório git.
Veja como o Git for Beancount funcionaPerguntas frequentes
O que saber antes de conectar.
Curioso sobre como é construído?
Leia o FAQ de engenharia no blogO 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 famílias de ferramentas especializadas — o manifesto de descubrimento legível por máquina em beancount.io/.well-known/ lista o conjunto atual. As ferramentas do ledger executam consultas Beancount Query Language (runBqlQuery), navegan pelo repositório (listLedgerFiles), leen documentos do ledger (readLedgerFiles) e criam, atualizam ou excluem arquivos em um commit atómico do git (editLedgerFiles, com modo de prévia dry_run). Outras ferramentas gestionan chaves de API (list, mint, revoke — a criação exige um plano pago e uma concessão OAuth, não uma chave de API) e conexões bancárias e importações (stage, submit ou discard de transações; um banco novo é vinculado no navegador, não via MCP). A IA os combina para responder perguntas e propor edições.
A IA pode modificar meu ledger sem eu saber?
As edições passam pelo tool editLedgerFiles. Um modo dry_run prévisualiza as operações de arquivo planeadas sem commitear nada, e se seu cliente pede confirmación antes de um commit real depende do cliente. Cada cambio commitado aterriza como un commit git real — um trilha de auditoria completa que puede revertir com herramientas git estándar. O caminho de commit pode reportar erros de validación após a escritura, então prévisualize primeiro e verifique o ledger depois.
Meus dados são enviados a terceiros?
Os dados do seu livro-razão passam pelo backend do Web Beancount e retornam como resultados de ferramentas para o seu cliente de IA. O modelo de IA que você escolher recebe esses resultados, portanto, as políticas de dados do provedor também se aplicam. Cada sessão autorizada é limitada a um livro-razão.
Traga seu livro-razão para a sua próxima conversa.
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.