Pergunte ao seu assistente de IA quanto você gastou no mês passado, quais contas precisam de conciliação ou onde uma transação pertence. O Beancount MCP dá a ele acesso às consultas, contas e arquivos-fonte do seu livro-razão hospedado, para que ele possa trabalhar com base nos seus registros e mostrar as evidências por trás da resposta.
Com permissão de escrita, o assistente também pode adicionar transações e atualizar arquivos do livro-razão. Você pode pedir que ele pré-visualize edições suportadas, revise as entradas propostas e verifique o livro-razão após uma alteração.
MCP significa Model Context Protocol: um padrão para conectar aplicativos de IA a ferramentas e dados externos. Essa conexão funciona com livros-razão hospedados no Beancount.io. As respostas do seu assistente refletem as transações e os preços registrados lá; conectar o MCP não atualiza automaticamente esses registros.
Conecte seu cliente de IA
Use um cliente que suporte MCP remoto via Streamable HTTP. A URL do servidor é:
https://beancount.io/api-gateway/mcpClaude Code
Adicione o servidor pelo seu terminal:
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpAbra o Claude Code, execute /mcp, selecione beancount e siga o fluxo de autenticação. Entre no Beancount.io e revise as permissões solicitadas. Volte ao /mcp para confirmar a conexão. Veja as instruções de MCP do Claude Code para detalhes específicos do cliente.
A página de consentimento permite restringir o acesso a um livro-razão ou escolher explicitamente Todos os livros-razão acessíveis. Uma restrição de livro-razão único é um bom ponto de partida. Com acesso mais amplo, diga ao assistente qual livro-razão usar, como alice/personal; as ferramentas do livro-razão devem identificar seu alvo em cada chamada.
Claude Desktop e Claude na web
Abra Personalizar → Conectores, escolha Adicionar conector personalizado, insira a URL do servidor e conecte sua conta do Beancount.io. Ative o conector para a conversa em que deseja usá-lo. Contas de organização podem precisar que um proprietário adicione o conector primeiro. Siga o guia de conectores remotos do Claude.
Cursor
Adicione o servidor ao seu ~/.cursor/mcp.json pessoal:
{
"mcpServers": {
"beancount": {
"url": "https://beancount.io/api-gateway/mcp"
}
}
}Conclua o login OAuth quando o Cursor solicitar e verifique se as ferramentas do servidor estão disponíveis. A documentação de MCP do Cursor cobre configuração e configurações de aprovação de ferramentas.
Chaves de API pessoais
Para um cliente que aceita credenciais bearer, você pode criar uma chave de API pessoal em Configurações → Tokens de acesso pessoal. Criar uma chave requer um plano pago do Beancount.io. Selecione ledger.read para consultas, restrinja opcionalmente a chave a um livro-razão e copie-a quando for exibida. Configure o cabeçalho de autorização do seu cliente como Authorization: Bearer SUA_CHAVE usando as configurações de credenciais privadas dele.
Mantenha a chave fora da configuração compartilhada do projeto. Clientes OAuth gerenciam credenciais pelo fluxo de login; você não precisa criar uma chave pessoal para esse caminho.
Comece com uma pergunta sobre gastos
Teste isso após conectar, substituindo o nome do livro-razão pelo seu:
Use
alice/personal. Identifique suas contas e moedas e resuma as despesas de agosto de 2026 por conta. Mostre o intervalo de datas e o BQL por trás de cada total, mantenha as moedas separadas e relate quaisquer erros de validação do livro-razão. Não altere nada.
O assistente pode descobrir seus livros-razão com listLedgers, aprender seus nomes de contas por meio de getLedgerContext e executar runBqlQueryStructured para resultados de consulta tipados. checkLedger retorna erros de validação, contagens de entradas e o commit mais recente.
Uma resposta útil inclui o livro-razão, período, moedas, totais e consultas de apoio. Para uma pergunta sobre patrimônio líquido, peça também o método de avaliação e as datas dos preços usados. Transações ausentes ou preços desatualizados podem mudar a resposta mesmo quando o livro-razão passa na validação.
Adicione uma transação com pré-visualização
Para novas entradas, appendLedgerText aceita texto Beancount comum e roteia diretivas para arquivos usando a configuração do seu livro-razão. A opção dry_run retorna um diff e erros de validação projetados antes de fazer commit.
Por exemplo:
Prepare uma compra de café de 4,50 USD datada de 15 de setembro de 2026, paga de
Assets:Cashe categorizada emExpenses:Food. Verifique se essas contas existem e procure uma transação correspondente primeiro. UseappendLedgerTextcomdry_run: true, mostre a entrada proposta e o diff do arquivo, e aguarde minha confirmação.
Com essas contas já abertas, a entrada proposta ficaria assim:
2026-09-15 * "Cafe" "Coffee"
Expenses:Food 4.50 USD
Assets:Cash -4.50 USDUse nomes de contas do seu próprio livro-razão e conclua a revisão:
- Verifique a data, o valor, as contas e o arquivo de destino na pré-visualização.
- Confirme a alteração exata que deseja que o assistente aplique.
- Peça que ele execute
checkLedgere relate o commit resultante e quaisquer erros.
appendLedgerText rejeita novos erros de validação por padrão. Alterações gerais em arquivos usam editLedgerFiles, que pode criar, substituir, atualizar ou excluir arquivos em um único commit Git. A pré-visualização também relata um diff e erros projetados. Verifique o resultado e execute checkLedger após a escrita: um commit bem-sucedido ainda pode conter erros contábeis.
Use um fluxo de trabalho para contabilidade recorrente
O servidor também fornece prompts MCP reutilizáveis. Clientes com suporte a prompts os exibem no seletor de comandos ou prompts:
| Fluxo de trabalho | Para que ajuda |
|---|---|
spending-report | Responder a uma pergunta sobre gastos com BQL de apoio e sem escrita no livro-razão. |
reconcile-account | Comparar uma conta com um extrato fornecido, classificar diferenças e propor entradas ausentes. |
close-month | Revisar contas ativas, asserções de saldo, transações recorrentes e sinalizações não resolvidas. |
categorize-imports | Revisar transações bancárias em estágio e propor categorias usando contas existentes. |
Esses prompts guiam o assistente por um procedimento. Eles não executam um trabalho contábil apenas por serem selecionados e não concedem permissões adicionais.
A conciliação exige um extrato e um saldo final. Um resultado de validação limpo por si só não pode estabelecer que toda transação foi registrada. Peça ao assistente para identificar qualquer coisa que não pôde verificar e deixe essas questões visíveis no relatório.
Para importações bancárias, vincule o banco no Beancount.io primeiro. Ler detalhes da conexão requer acesso administrativo; enviar transações em estágio requer permissão de escrita e o acesso apropriado a essa conexão bancária. Revise categorias propostas e duplicatas antes de autorizar o envio.
Entenda acesso e tratamento de dados
As permissões da conexão determinam o que o assistente pode fazer:
| Permissão | Acesso |
|---|---|
ledger.read | Consultar e ler dados do livro-razão. |
ledger.write | Ler dados e fazer alterações comuns no livro-razão. |
ledger.admin | Ler, escrever e realizar operações administrativas onde autorizado. |
Seu acesso existente a cada livro-razão ainda se aplica. Restringir uma credencial a um livro-razão impede que chamadas do livro-razão atinjam outro; uma credencial sem restrição pode selecionar entre os livros-razão que você pode acessar. O cliente OAuth escolhe quais permissões solicitar, então leia a tela de consentimento antes de aprovar.
O servidor MCP não exibe uma caixa de diálogo de aprovação humana. As configurações do seu cliente determinam quando ele pergunta antes de chamar uma ferramenta, e pré-visualizações devem ser solicitadas explicitamente. Os fluxos de trabalho de escrita fornecidos instruem o assistente a aguardar confirmação. Uma credencial restrita a ledger.read fornece uma fronteira imposta quando você quer análise sem escrita.
Resultados de ferramentas, incluindo transações consultadas e arquivos que o assistente lê, entram no contexto do seu cliente de IA e podem ser processados pelo provedor de modelo dele. O Beancount.io retém seu livro-razão, histórico Git e registros operacionais. Uma conexão MCP sem estado não é uma promessa de que nenhum dado é retido; as políticas de dados do seu cliente e provedor também se aplicam.
Chaves de API pessoais revogadas são rejeitadas em solicitações subsequentes. Tokens de acesso OAuth normalmente duram uma hora; revogar um token de atualização não invalida imediatamente um token de acesso já emitido. O acesso ao livro-razão é verificado novamente quando operações protegidas são executadas.
Perguntas comuns
Isso abre o livro-razão no meu laptop?
O endpoint hospedado opera no seu livro-razão do Beancount.io. Ele não abre um arquivo .bean local e você não precisa ter uma aba do navegador Fava aberta.
Como isso é diferente do assistente de IA do painel?
O painel fornece sua própria interface de chat. O MCP disponibiliza capacidades do livro-razão a partir de um cliente de IA externo, com a conversa, o modelo e as configurações de aprovação desse cliente.
Por que posso ver uma ferramenta, mas não usá-la?
O catálogo de ferramentas inclui operações que sua credencial pode não permitir. Verifique o erro e as permissões concedidas. Uma credencial sem restrição também precisa de um alvo de livro-razão explícito para ferramentas do livro-razão.
Conecte seu livro-razão e comece com uma pergunta que você possa verificar em seus registros. Mantenha a consulta junto com a resposta e adicione permissões de escrita quando quiser ajuda para manter o próprio livro-razão.
