Beancount MCP: Connect Your Ledger to AI Assistants

Ask your AI assistant how much you spent last month, which accounts need reconciling, or where a transaction belongs. Beancount MCP gives it access to your hosted ledger's queries, accounts, and source files, so it can work from your books and show the evidence behind its answer.

With write permission, the assistant can also add transactions and update ledger files. You can ask it to preview supported edits, review the proposed entries, and check the ledger after a change.

MCP stands for Model Context Protocol: a standard for connecting AI applications to external tools and data. This connection works with ledgers hosted on Beancount.io. Your assistant's answers reflect the transactions and prices recorded there; connecting MCP does not automatically make those records current.

Connect your AI client​

Use a client that supports remote MCP over Streamable HTTP. The server URL is:

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

Claude Code​

Add the server from your terminal:

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

Open Claude Code, run /mcp, select beancount, and follow its authentication flow. Sign in to Beancount.io and review the requested permissions. Return to /mcp to confirm the connection. See Claude Code's MCP instructions for client-specific details.

The consent page lets you restrict access to one ledger or explicitly choose All accessible ledgers. A single-ledger restriction is a useful starting point. With broader access, tell the assistant which ledger to use, such as alice/personal; ledger tools must identify their target on each call.

Claude Desktop and Claude on the web​

Open Customize → Connectors, choose Add custom connector, enter the server URL, and connect your Beancount.io account. Enable the connector for the conversation where you want to use it. Organization accounts may need an owner to add the connector first. Follow Claude's remote connector guide.

Cursor​

Add the server to your personal ~/.cursor/mcp.json:

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

Complete the OAuth sign-in when Cursor requests it, then check that the server's tools are available. Cursor's MCP documentation covers configuration and tool approval settings.

Personal API keys​

For a client that accepts bearer credentials, you can create a personal API key in Settings → Personal access tokens. Creating a key requires a paid Beancount.io plan. Select ledger.read for queries, optionally restrict the key to one ledger, and copy it when it is shown. Configure your client's authorization header as Authorization: Bearer YOUR_KEY using its private credential settings.

Keep the key out of shared project configuration. OAuth clients manage credentials through their sign-in flow; you do not need to create a personal key for that path.

Start with a spending question​

Try this after connecting, replacing the ledger name with yours:

Use alice/personal. Identify its accounts and currencies, then summarize August 2026 expenses by account. Show the date range and BQL behind each total, keep currencies separate, and report any ledger validation errors. Do not change anything.

The assistant can discover your ledgers with listLedgers, learn your account names through getLedgerContext, and run runBqlQueryStructured for typed query results. checkLedger returns validation errors, entry counts, and the latest commit.

A useful answer includes the ledger, period, currencies, totals, and supporting queries. For a net-worth question, also ask for the valuation method and the dates of the prices used. Missing transactions or stale prices can change the answer even when the ledger passes validation.

Add a transaction with a preview​

For new entries, appendLedgerText accepts ordinary Beancount text and routes directives to files using your ledger's configuration. Its dry_run option returns a diff and projected validation errors before committing.

For example:

Prepare a 4.50 USD coffee purchase dated September 15, 2026, paid from Assets:Cash and categorized under Expenses:Food. Check that those accounts exist and look for a matching transaction first. Use appendLedgerText with dry_run: true, show the proposed entry and file diff, and wait for my confirmation.

With those accounts already open, the proposed entry would look like this:

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

Use account names from your own ledger, then complete the review:

1. Check the date, amount, accounts, and destination file in the preview.
2. Confirm the exact change you want the assistant to apply.
3. Ask it to run checkLedger and report the resulting commit and any errors.

appendLedgerText rejects new validation errors by default. General file changes use editLedgerFiles, which can create, replace, update, or delete files in one Git commit. Its preview also reports a diff and projected errors. Check the result and run checkLedger after writing: a successful commit can still contain accounting errors.

Use a workflow for recurring bookkeeping​

The server also provides reusable MCP prompts. Clients with prompt support expose them in their command or prompt picker:

These prompts guide the assistant through a procedure. They do not run an accounting job merely because you select them, and they do not grant additional permissions.

Reconciliation needs a statement and an ending balance. A clean validation result alone cannot establish that every transaction has been recorded. Ask the assistant to identify anything it could not verify and leave those questions visible in the report.

For bank imports, link the bank in Beancount.io first. Reading connection details requires administrative access; submitting staged transactions requires write permission and the appropriate access to that bank connection. Review proposed categories and duplicates before authorizing submission.

Understand access and data handling​

The connection's permissions determine what the assistant can do:

Your existing access to each ledger still applies. Restricting a credential to one ledger prevents ledger calls from targeting another; an unrestricted credential can select among the ledgers you can access. The OAuth client chooses which permissions to request, so read the consent screen before approving.

The MCP server does not display a human approval dialog. Your client's settings determine when it asks before calling a tool, and previews must be requested explicitly. The supplied writing workflows instruct the assistant to wait for confirmation. A credential restricted to ledger.read provides an enforced boundary when you want analysis without writes.

Tool results, including queried transactions and files the assistant reads, enter your AI client's context and may be processed by its model provider. Beancount.io retains your ledger, Git history, and operational records. A stateless MCP connection is not a promise that no data is retained; your client's and provider's data policies also apply.

Revoked personal API keys are rejected on subsequent requests. OAuth access tokens normally last one hour; revoking a refresh token does not immediately invalidate an access token already issued. Ledger access is checked again when protected operations run.

Common questions​

Does this open the ledger on my laptop?

The hosted endpoint operates on your Beancount.io ledger. It does not open a local .bean file, and you do not need a Fava browser tab open.

How is this different from the dashboard's AI assistant?

The dashboard provides its own chat interface. MCP makes ledger capabilities available from an external AI client, with that client's conversation, model, and approval settings.

Why can I see a tool but not use it?

The tool catalog includes operations your credential may not permit. Check the error and the granted permissions. An unrestricted credential also needs an explicit ledger target for ledger tools.

Connect your ledger and begin with one question you can verify against your books. Keep the query with the answer, then add write permissions when you want help maintaining the ledger itself.