Skip to main content
Beancount.io Logo

Model Context Protocol

Your ledger, in the conversation.

Connect Beancount to the AI tools you already use. Ask about your finances, work with your ledger files, and keep changes traceable in Git.

Connect your AI clientRead the announcement

Just ask

Start with a question. Follow the answer back to your ledger.

Example data, not a live connection.
You

What's my net worth today?

Your AI assistant

Your net worth today is 128,450.32 USD.

Query the balances in your ledger, then check the results behind the answer.
Behind the answer
runBqlQuery
SELECT sum(position) WHERE account ~ 'Assets|Liabilities'
Beancount
An illustrative MCP conversation

Works with your MCP-compatible client

  • Claude Code
  • Claude Desktop
  • Cursor
  • Windsurf
  • Zed

Connect the client you already use

Choose your client, add the server, and authorize one ledger.

Claude Code

  1. Run this one command in your terminal.

  2. Open Claude Code and run /mcp to authenticate. Sign in to Web Beancount and choose your ledger.

  3. Approve once. Credentials refresh automatically from here.

Client setup documentation
Terminal
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcp

Have more than one ledger? Add the server again under a different name and authorize the other ledger in its own prompt:

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

Use your Web Beancount account to authorize access to a single ledger.

What the AI can do

The server exposes focused tools for your ledger, your API keys, and your bank connections — the ledger verbs are shown below. The AI composes them: discover your file structure, read for context, query for answers, propose an edit.

Ledger, API-key, and bank tools. Your client decides how to use them.

runBqlQuery

Run BQL (Beancount Query Language) queries against balances, transactions, and accounts.

listLedgerFiles

Browse the directory structure of your ledger repository.

readLedgerFiles

Read the contents of your .beancount files and other ledger documents.

editLedgerFiles

Create, update, replace, or delete files in an atomic git commit.

Your ledger, guarded

An AI with write access to your books earns trust through design, not promises.

Ledger-scoped OAuth 2.1

One session is authorized for exactly one ledger. A session for your personal ledger cannot touch your business ledger — blast radius, limited.

Dry-run previews

editLedgerFiles supports a dry_run mode that validates and previews the exact changes without writing anything, so your client can show you a diff first.

Every edit is a git commit

Changes land as real commits ("AI edit: …") in your ledger's repository — a full audit trail you can review and revert with standard git tools.

Stateless server

The MCP server keeps no session state between tool calls. Your chosen AI client and model receive the results you request; check their data policies before connecting.

Your whole ledger is a git repository already.

See how Git for Beancount works

Frequently asked questions

What to know before you connect.

Curious how it's built?

Read the engineering FAQ on the blog
What is MCP and why does it matter for Beancount?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools and data sources in a structured, safe way. Instead of guessing or asking you to paste data, your AI client connects directly to your ledger — it queries your real data, reads your actual files, and makes precise edits.

Which AI clients work with the Beancount MCP server?

Any MCP-compatible client that supports OAuth 2.1 works out of the box, including Claude Code, Claude Desktop, Cursor, Windsurf, and Zed. Clients without OAuth 2.1 support can connect with a static token generated in your beancount.io account settings.

How do I connect my ledger?

Add the server URL to your client's MCP configuration. On first use the client opens a browser window — log in with your Web Beancount account and pick the ledger you want to grant access to. The client stores and refreshes credentials automatically from there.

What can the AI actually do with my ledger?

The server exposes focused tool families — the machine-readable discovery manifest under beancount.io/.well-known/ lists the current set. Ledger tools run Beancount Query Language queries (runBqlQuery), browse the repository (listLedgerFiles), read ledger documents (readLedgerFiles), and create, update, or delete files in an atomic git commit (editLedgerFiles, with a dry_run preview mode). Further tools manage API keys (list, mint, revoke — minting needs a paid plan and an OAuth grant, not an API key) and bank connections and imports (stage, submit, or discard transactions; a brand-new bank is linked in the browser, not over MCP). The AI combines them to answer questions and propose edits.

Can the AI modify my ledger without me knowing?

Edits go through the editLedgerFiles tool. A dry_run mode previews the planned file operations without committing anything, and whether your client asks before a real commit depends on the client. Every committed change lands as a real git commit — a full audit trail you can revert with standard git tools. The commit path can report validation errors after the write, so preview first and verify the ledger afterwards.

Is my data sent to a third party?

Your ledger data passes through the Web Beancount backend and returns as tool results to your AI client. The AI model you choose receives those results, so its provider’s data policies also apply. Each authorized session is scoped to one ledger.

Bring your ledger into your next conversation.

The Beancount MCP server is available today to all Web Beancount users. Your ledger is one git push away.

Get started freeConnect your client