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 uma vez e autorize os ledgers que ele pode acessar.
Claude Code
Execute este comando no seu terminal.
Abra o Claude Code e execute /mcp para autenticar. Faça login no Web Beancount e aprove um ledger ou todos eles.
Aprove uma vez. As credenciais são renovadas automaticamente a partir daqui.
Terminal
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpMais de um ledger? Aprove todos de uma vez. O assistente chama listLedgers para ver o que pode acessar e nomeia o ledger em cada chamada, então um único servidor cobre todos os livros.
Use sua conta Web Beancount para autorizar quais ledgers o servidor pode acessar.
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 específicas para o seu ledger e as suas conexões bancárias — os verbos do ledger aparecem abaixo. A IA as combina: descobrir a estrutura dos seus arquivos, ler o contexto, consultar respostas, propor uma edição.
Ferramentas de ledger e de banco. 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.
updateLedgerFiles
Altera arquivos em um commit git atômico, com pré-visualização dry_run; createLedgerFiles e deleteLedgerFiles os adicionam e removem.
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
Você escolhe o que uma conexão pode acessar: um único ledger ou todos eles. Autorize apenas seu ledger pessoal e a conexão não poderá tocar nos seus livros comerciais — você define o raio de impacto.
Pré-visualizações em modo de teste
As ferramentas de arquivos (createLedgerFiles, updateLedgerFiles, deleteLedgerFiles) e o appendLedgerText oferecem um modo dry_run que valida e pré-visualiza as alterações exatas sem gravar nada, para que seu cliente possa mostrar um diff primeiro.
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 blogEstá avaliando outros servidores MCP de contabilidade?
Como o Beancount MCP se compara ao QuickBooks, Xero e ExpensifyO 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 de MCP do seu cliente. No primeiro uso, o cliente abre uma janela do navegador — faça login com sua conta Web Beancount e escolha se ele pode acessar um único ledger ou todos eles. 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 uma ferramenta por operação — o manifesto de descoberta legível por máquina em beancount.io/.well-known/ lista o conjunto atual. As ferramentas de ledger executam consultas em Beancount Query Language (runBqlQuery), navegam pelo repositório (listLedgerFiles), leem documentos do ledger (readLedgerFiles), adicionam diretivas em ordem de data (appendLedgerText) e criam, alteram ou excluem arquivos em um commit git atômico (createLedgerFiles, updateLedgerFiles, deleteLedgerFiles, cada uma com um modo de pré-visualização dry_run). As ferramentas bancárias buscam, importam ou descartam transações pendentes e gerenciam as conexões vinculadas; um banco novo é vinculado no navegador, não pelo MCP. As chaves de API e as configurações da conta ficam no aplicativo web do Beancount.io. A IA combina as ferramentas para responder perguntas e propor edições.
A IA pode modificar meu ledger sem eu saber?
Novas diretivas passam pelo appendLedgerText, e alterações de arquivos pelas ferramentas de arquivos — createLedgerFiles, updateLedgerFiles, deleteLedgerFiles. Um modo dry_run pré-visualiza as alterações planejadas sem confirmar nada, e se o seu cliente pergunta antes de um commit real depende do cliente. Cada alteração confirmada vira um commit git real — uma trilha de auditoria completa que você pode reverter com as ferramentas git padrão. O processo de commit pode relatar erros de validação depois da gravação, então pré-visualize primeiro e verifique o ledger depois.
Meus dados são enviados a terceiros?
Os dados do seu razão passam pelo backend do Web Beancount e retornam como resultados de ferramentas para seu cliente de IA. O modelo de IA que você escolher recebe esses resultados, portanto as políticas de dados do provedor dele também se aplicam. Uma conexão acessa apenas os razões que você autorizou: um único razão, ou todos eles.
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.