Beancount MCP: conecte seu livro-razão ao Claude, Cursor e qualquer assistente de IA

O Web Beancount lança o servidor MCP — converse com seu livro-razão a partir do Claude, do Cursor e de qualquer ferramenta de IA que você já usa

Seus dados contábeis encontram seu fluxo de trabalho com IA. Sem copiar e colar. Sem exportações. Basta perguntar.

Hoje, o Web Beancount anuncia o Servidor Beancount MCP — um endpoint do Model Context Protocol (MCP) que permite conectar seu livro-razão Beancount diretamente ao Claude Desktop, Claude Code, Cursor, Windsurf ou qualquer outro cliente de IA compatível com MCP. Pela primeira vez, usuários avançados podem fazer perguntas contábeis, executar consultas BQL e até editar arquivos do livro-razão de dentro das ferramentas de IA que já usam no dia a dia — sem trocar de aba ou sair do fluxo de trabalho.

Os arquivos Beancount em texto simples são poderosos justamente porque são apenas arquivos. Mas responder "quanto gastei com viagens no último trimestre?" ainda exige conhecer a sintaxe do BQL, saber onde estão seus arquivos e copiar os resultados para um chat. O servidor Beancount MCP elimina essa fricção por completo.

Com o servidor Beancount MCP configurado no seu cliente de IA, você pode:

Perguntar "Qual é o meu patrimônio líquido hoje?" e obter uma resposta ao vivo extraída do seu livro-razão real
Solicitar um resumo das despesas do mês passado e deixar a IA escrever a consulta BQL para você
Pedir à IA para adicionar uma transação e vê-la confirmar a alteração no repositório git do seu livro-razão
Navegar e ler seus arquivos .beancount sem nunca sair do seu editor

O servidor tem escopo de livro-razão: cada sessão MCP é autorizada para exatamente um livro-razão usando OAuth 2.1. Clientes como o Claude Code descobrem e concluem o fluxo de autorização automaticamente — sem necessidade de gerenciar tokens manualmente. Seu livro-razão permanece onde já vive, no backend do Web Beancount: o cliente de IA envia chamadas de ferramentas estruturadas ao nosso servidor, que lê ou edita seu livro-razão em seu nome e retorna os resultados. O próprio servidor MCP não armazena nada além do que a conversa do seu cliente de IA já contém.

O servidor Beancount MCP está disponível hoje para todos os usuários do Web Beancount.

Comece agora

O servidor Beancount MCP está no ar. Adicione-o ao seu cliente de IA em menos de um minuto.

URL do servidor MCP

https://beancount.io/api-gateway/mcp

Claude Code (recomendado — fluxo OAuth 2.1 completo, sem necessidade de token)

claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

No primeiro uso, o Claude Code abrirá uma janela do navegador. É no prompt do navegador que você escolhe qual livro-razão conectar — aprove uma vez e as credenciais serão renovadas automaticamente. Tem mais de um livro-razão? Adicione o servidor novamente com um nome diferente (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) e autorize o outro livro-razão em seu próprio prompt.

Claude Desktop / Cursor / Windsurf / Zed

Adicione o servidor à configuração MCP do seu cliente (claude_desktop_config.json ou equivalente). Clientes com suporte a OAuth 2.1 abrem o mesmo prompt do navegador no primeiro uso — escolha seu livro-razão ali:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp"
    }
  }
}

Se o seu cliente ainda não oferece suporte ao fluxo OAuth, gere um token estático (com escopo de um único livro-razão) nas configurações da sua conta beancount.io e passe-o como um cabeçalho:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Ainda não tem uma conta no Web Beancount? Cadastre-se em beancount.io — seu livro-razão está a um git push de distância.

Perguntas frequentes

Perguntas de clientes

O que é o MCP e por que ele importa para o Beancount?

O 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. Pense nele como uma porta USB para IA: em vez de a IA adivinhar ou pedir que você cole dados, ela se conecta diretamente aos seus sistemas. Para usuários do Beancount, isso significa que seu cliente de IA pode consultar os dados reais do seu livro-razão, ler seus arquivos de verdade e fazer edições precisas — sem adivinhar o que eles podem conter.

Quais clientes de IA funcionam com o servidor Beancount MCP?

Qualquer cliente compatível com MCP que suporte OAuth 2.1 funciona imediatamente. O servidor Beancount MCP implementa o fluxo completo de autorização OAuth 2.1 com PKCE, de modo que clientes como o Claude Code descobrem automaticamente o endpoint de autorização do servidor e solicitam que você faça login — sem necessidade de copiar tokens ou configurar nada manualmente. Depois que você aprova o acesso, o cliente armazena e renova as credenciais automaticamente.

Clientes com suporte conhecido a MCP + OAuth 2.1 incluem Claude Code CLI, Claude Desktop, Cursor, Windsurf e Zed. À medida que o ecossistema MCP cresce, qualquer novo cliente que siga a especificação MCP OAuth 2.1 funcionará sem alterações do nosso lado.

Como conecto meu livro-razão?

Para clientes que suportam OAuth 2.1 (como o Claude Code):

Adicione a URL do servidor Beancount MCP à configuração MCP do seu cliente.
O cliente abre automaticamente uma janela do navegador para autorizar o acesso.
Faça login com sua conta do Web Beancount e escolha o livro-razão ao qual deseja conceder acesso.
Pronto — a partir daqui, o cliente cuida do armazenamento e da renovação do token.

Para clientes sem suporte a OAuth 2.1, gere um token estático (com escopo de um único livro-razão) nas configurações da sua conta do Web Beancount e passe-o como um cabeçalho Authorization: Bearer.

Isto é a mesma coisa que o recurso de chat "Ask AI" no painel?

Eles compartilham as mesmas ferramentas de livro-razão por baixo (consultas BQL, leitura/escrita de arquivos), mas o servidor MCP é um ponto de entrada diferente. O recurso Ask AI do painel é uma experiência de chat hospedada, com um sandbox do Claude Code apoiado pela Cloudflare. O servidor MCP é um endpoint de protocolo ao qual você se conecta a partir do seu próprio cliente de IA de preferência — dando a você mais controle, mais modelos e uma integração mais profunda com o seu fluxo de trabalho existente.

O que a IA pode realmente fazer com o meu livro-razão?

O servidor MCP expõe quatro ferramentas:

Ferramenta	O que ela faz
`runBqlQuery`	Executa BQL (Beancount Query Language) para consultar saldos, transações e contas
`listLedgerFiles`	Navega pela estrutura de diretórios do repositório do seu livro-razão
`readLedgerFiles`	Lê o conteúdo de arquivos `.beancount` e outros documentos do livro-razão
`editLedgerFiles`	Cria, atualiza, substitui ou exclui arquivos em um commit git atômico

A IA pode combiná-las: descobrir a estrutura dos seus arquivos, ler arquivos relevantes para obter contexto, escrever uma consulta BQL para responder à sua pergunta ou propor e confirmar uma edição.

A IA pode modificar meu livro-razão sem eu saber?

As edições de arquivos exigem que o cliente de IA chame editLedgerFiles com uma descrição do que está sendo alterado. Clientes MCP bem-comportados (incluindo o Claude Code) mostram isso a você antes de executar. As edições também suportam um modo dry_run que pré-visualiza as alterações exatas sem escrever nada, para que seu cliente possa mostrar um diff primeiro. E toda alteração confirmada é um commit git real no repositório do seu livro-razão, então você tem uma trilha de auditoria completa e pode reverter qualquer coisa com as ferramentas git padrão.

Meus dados são enviados a terceiros?

Os dados do seu livro-razão passam pelo backend do Web Beancount (que já gerencia seu livro-razão) e são retornados como resultados estruturados ao seu cliente de IA. O modelo de IA que você usa (por exemplo, o Claude) recebe os resultados das ferramentas como qualquer outro contexto. Nenhum dado é armazenado pelo servidor MCP além do que a conversa do seu cliente de IA já contém.

Cada token tem escopo de livro-razão — o que isso significa?

Ao autorizar o servidor MCP, você escolhe a qual livro-razão conceder acesso. Aquela sessão só pode acessar aquele livro-razão. Se você tiver vários livros-razão, autoriza sessões separadas. Isso limita o raio de impacto: uma sessão do seu livro-razão pessoal não pode tocar no seu livro-razão empresarial.

O servidor MCP exige que a interface web do Fava esteja em execução?

Não. O servidor MCP se comunica com a API interna do Fava gerenciada pela infraestrutura do Web Beancount (o Fava é a interface web que alimenta seu livro-razão da beancount.io). Você não precisa manter a interface do Fava aberta ou acessível.

O que acontece se eu revogar meu acesso ao MCP?

As sessões MCP em andamento receberão erros 401 na próxima chamada de ferramenta. Clientes que suportam OAuth 2.1 tentarão reautorizar automaticamente, solicitando que você faça login novamente.

Nos bastidores

Para os curiosos em tecnologia — como o servidor é construído.

Por que MCP em vez de construir nossa própria API/plugin para cada ferramenta de IA?

O MCP é o padrão emergente e já é suportado por todos os principais editores de IA. Construir um único servidor MCP em conformidade nos dá compatibilidade com todo o ecossistema de uma só vez, em vez de manter integrações separadas para Claude, Cursor, Windsurf e o que quer que seja lançado no próximo trimestre. O protocolo cuida da descoberta, dos esquemas de ferramentas e do streaming — nós nos concentramos na lógica de domínio.

Por que OAuth 2.1 em vez de chaves de API estáticas?

OAuth 2.1 com PKCE é o que a especificação MCP recomenda para servidores remotos, e é o que clientes como o Claude Code implementam nativamente. O benefício prático: os usuários nunca tocam em um token. O cliente descobre o servidor de autorização por meio do nosso endpoint de metadados .well-known/oauth-protected-resource, conclui o PKCE e gerencia a renovação automaticamente. Tokens estáticos continuam sendo suportados como alternativa para clientes que ainda não implementaram o fluxo completo.

Por que Streamable HTTP em vez do transporte SSE ou stdio?

O Streamable HTTP é o transporte MCP projetado para servidores remotos sobre HTTPS. O stdio é para processos locais. O SSE (o transporte MCP mais antigo) está sendo descontinuado em favor do Streamable HTTP. Nossos usuários se conectam a partir de clientes de IA que não estão no mesmo local que o nosso servidor, então o Streamable HTTP é a escolha correta e voltada para o futuro.

Por que a sessão MCP é stateless (sem sessionIdGenerator)?

Definimos sessionIdGenerator: undefined para tornar cada requisição totalmente stateless — nenhum estado de sessão do lado do servidor é alocado ou retido entre as chamadas de ferramentas. Isso corresponde ao modo stateless da especificação Streamable HTTP e mantém o servidor escalável horizontalmente sem afinidade de sessão. O contexto da ferramenta (identidade do livro-razão, cliente da API do Fava) é reconstruído a cada requisição a partir do token OIDC validado.

Como funciona a verificação de acesso ao livro-razão?

Após a validação do token OIDC, resolveLedgerAccess verifica, por meio da API do Fava, se o usuário autenticado realmente tem acesso ao livro-razão solicitado. Isso impede que um token válido para um livro-razão seja usado para sondar o livro-razão de outro usuário (defesa em profundidade sobre o token assinado).

Onde editLedgerFiles faz o commit?

Ela chama changeLedgerFiles na API do Fava, que cria um commit git no repositório Gitea do livro-razão com a mensagem AI edit: <description>. A descrição vem do campo description que a IA preenche — mostrada ao usuário em clientes MCP bem-comportados antes da execução.

O que é a opção dry_run em editLedgerFiles?

dry_run: true valida todas as operações de arquivo (verifica se os arquivos existem, confirma que as strings antigas de str_replace correspondem exatamente uma vez) e retorna uma prévia do que seria confirmado — sem realmente escrever no git. Isso é útil para clientes de IA que querem mostrar um diff ao usuário antes de confirmar.

Qual é a superfície de erros visível para os clientes de IA?

Os erros de ferramentas são retornados como { isError: true, content: [{ type: "text", text: "..." }] } — o formato de erro estruturado do SDK do MCP. O cliente de IA recebe a mensagem de erro como texto e pode decidir como tratá-la (tentar novamente, reportar ao usuário etc.). As falhas de autenticação no nível HTTP (401) incluem um cabeçalho WWW-Authenticate apontando para os metadados do recurso protegido OAuth, de modo que clientes em conformidade possam reiniciar automaticamente o fluxo de autorização.