runBqlQuery
Run BQL (Beancount Query Language) queries against balances, transactions, and accounts.
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.
Just ask
Start with a question. Follow the answer back to your ledger.
Behind the answer
runBqlQuerySELECT sum(position) WHERE account ~ 'Assets|Liabilities'Beancount
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 once, and authorize the ledgers it may reach.
Claude Code
Run this one command in your terminal.
Open Claude Code and run /mcp to authenticate. Sign in to Web Beancount and approve one ledger or all of them.
Approve once. Credentials refresh automatically from here.
Terminal
claude mcp add --transport http beancount https://beancount.io/api-gateway/mcpMore than one ledger? Approve them all once. The assistant calls listLedgers to see what it can reach and names the ledger on each call, so a single server covers every book.
Use your Web Beancount account to authorize which ledgers the server may reach.
Don't have a Web Beancount account? Sign up at beancount.io — your ledger is one git push away.
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.
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.
Scoped OAuth 2.1
You choose what a connection can reach: a single ledger, or all of them. Authorize only your personal ledger and the connection cannot touch your business books — you set the blast radius.
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 worksFrequently asked questions
What to know before you connect.
Curious how it's built?
Read the engineering FAQ on the blogWhat 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 choose whether it may reach a single ledger or all of them. 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.