# Beancount MCP: Conecte Seu Livro-razão a Assistentes de IA

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.

![Um laptop de argila conectado a um livro-razão verde aberto, com um recibo em uma bandeja de revisão e blocos vinculados representando o histórico do Git.](/img/blog/beancount-mcp/hero.webp)

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 é:

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

### Claude Code

Adicione o servidor pelo seu terminal:

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

Abra 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](https://code.claude.com/docs/en/mcp) 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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Adicione o servidor ao seu `~/.cursor/mcp.json` pessoal:

```json
{
  "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](https://cursor.com/docs/mcp) 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](https://beancount.io/settings/api-keys). **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:Cash` e categorizada em `Expenses:Food`. Verifique se essas contas existem e procure uma transação correspondente primeiro. Use `appendLedgerText` com `dry_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:

```beancount
2026-09-15 * "Cafe" "Coffee"
  Expenses:Food   4.50 USD
  Assets:Cash    -4.50 USD
```

Use nomes de contas do seu próprio livro-razão e conclua a revisão:

1. Verifique a data, o valor, as contas e o arquivo de destino na pré-visualização.
2. Confirme a alteração exata que deseja que o assistente aplique.
3. Peça que ele execute `checkLedger` e relate o commit resultante e quaisquer erros.

`appendLedgerText` rejeita novos erros de validação por padrão. Alterações gerais em arquivos usam `createLedgerFiles`, `updateLedgerFiles` e `deleteLedgerFiles`, que gravam seus arquivos em um único commit Git cada um. 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.
