Model Context Protocol
Talk to your ledger from the AI tools you already use
The Beancount MCP server connects your plain-text ledger to Claude Code, Claude Desktop, Cursor, Windsurf, Zed — any MCP-compatible AI client. No copy-paste. No exports. Just ask.
MCP server URL
https://beancount.io/api-gateway/mcp> What's my net worth today?
⏺ runBqlQuery("SELECT sum(position) WHERE account ~ 'Assets|Liabilities'")
Your net worth today is 128,450.32 USD.
> Add yesterday's 42 USD team dinner and commit it
⏺ editLedgerFiles(dry_run: true) → +1 transaction
⏺ git commit a1b4f2e — "AI edit: add team dinner transaction"
Done — committed to your ledger with a full audit trail.
Just ask
Answering "how much did I spend on travel last quarter?" used to mean knowing BQL syntax, finding the right files, and copying results into a chat. Now it's a sentence.
“What's my net worth today?”
A live answer drawn from your actual ledger — not a guess.
“Summarize last month's expenses”
The AI writes the BQL query for you and reads back the results.
“Add a transaction and commit it to git”
A real commit in your ledger's repository, revertable like any other.
“What's in my ledger repo?”
Browse and read your .beancount files without leaving your editor.
What the AI can do
The server exposes four ledger tools. The AI composes them: discover your file structure, read for context, query for answers, propose an edit.
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.
Get connected in under a minute
Pick your AI client. Copy. Paste. Ask.
- Run this one command in your terminal.
- Claude Code opens a browser window — log in and pick which ledger to connect.
- Approve once. Credentials refresh automatically from here.
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpHave 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/mcpDon't have a Web Beancount account? Sign up at beancount.io — your ledger is one git push away.
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.
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.
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.
Stateless server
The MCP server stores nothing beyond what your AI client's conversation already holds. Your ledger stays where it lives today.
Your whole ledger is a git repository already. See how Git for Beancount works
Frequently asked questions
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 four tools: runBqlQuery executes Beancount Query Language queries, listLedgerFiles browses your ledger repository, readLedgerFiles reads your ledger documents, and editLedgerFiles creates, updates, or deletes files in an atomic git commit. 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, which well-behaved MCP clients surface to you before executing. A dry_run mode previews the exact changes without writing anything, and every committed change is a real git commit — a full audit trail you can revert with standard git tools.
Is my data sent to a third party?
Your ledger data flows through the Web Beancount backend, which already manages your ledger, and returns as structured results to your AI client. Sessions are ledger-scoped: each one can access exactly the ledger you authorized, and the MCP server stores nothing beyond what your AI client's conversation holds.
Curious how it's built? Read the engineering FAQ on the blog
Your accounting data meets your AI workflow
The Beancount MCP server is available today to all Web Beancount users. Your ledger is one git push away.