Beancount MCP: Connect Your Ledger to Claude, Cursor, and Any AI Assistant

Web Beancount Launches MCP Server — Talk to Your Ledger from Claude, Cursor, and Any AI Tool You Already Use

Your accounting data meets your AI workflow. No copy-paste. No exports. Just ask.

Today, Web Beancount announces the Beancount MCP Server — a Model Context Protocol (MCP) endpoint that lets you connect your Beancount ledger directly to Claude Desktop, Claude Code, Cursor, Windsurf, or any other MCP-compatible AI client. For the first time, power users can ask accounting questions, run BQL queries, and even edit ledger files from inside the AI tools they already live in — without switching tabs or leaving their workflow.

Plain-text Beancount files are powerful precisely because they're just files. But answering "how much did I spend on travel last quarter?" still requires knowing BQL syntax, knowing where your files are, and copying results into a chat. The Beancount MCP server removes that friction entirely.

With the Beancount MCP server configured in your AI client, you can:

Ask "What's my net worth today?" and get a live answer drawn from your actual ledger
Request a summary of last month's expenses and have the AI write the BQL query for you
Tell the AI to add a transaction and watch it commit the change to your ledger's git repository
Browse and read your .beancount files without ever leaving your editor

The server is ledger-scoped: each MCP session is authorized for exactly one ledger using OAuth 2.1. Clients like Claude Code discover and complete the authorization flow automatically — no manual token management required. Your ledger stays where it already lives, on the Web Beancount backend: the AI client sends structured tool calls to our server, which reads or edits your ledger on your behalf and returns the results. The MCP server itself stores nothing beyond what your AI client's own conversation holds.

The Beancount MCP server is available today to all Web Beancount users.

Get Started

The Beancount MCP server is live. Add it to your AI client in under a minute.

MCP server URL

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

Claude Code (recommended — full OAuth 2.1 flow, no token needed)

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

On first use, Claude Code will open a browser window. The browser prompt is where you pick which ledger to connect — approve once, and credentials refresh automatically. Have more than one ledger? Add the server again under a different name (claude mcp add --transport http beancount-business https://beancount.io/api-gateway/mcp) and authorize the other ledger in its own prompt.

Claude Desktop / Cursor / Windsurf / Zed

Add the server to your client's MCP config (claude_desktop_config.json or equivalent). Clients with OAuth 2.1 support open the same browser prompt on first use — pick your ledger there:

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

If your client doesn't support the OAuth flow yet, generate a static token (scoped to one ledger) from your beancount.io account settings and pass it as a header:

{
  "mcpServers": {
    "beancount": {
      "url": "https://beancount.io/api-gateway/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Don't have a Web Beancount account? Sign up at beancount.io — your ledger is one git push away.

Frequently Asked Questions

Customer FAQs

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. Think of it as a USB port for AI: instead of the AI guessing or asking you to paste data, it connects directly to your systems. For Beancount users, this means your AI client can query your real ledger data, read your actual files, and make precise edits — not guess at what they might contain.

Which AI clients work with the Beancount MCP server?

Any MCP-compatible client that supports OAuth 2.1 works out of the box. The Beancount MCP server implements the full OAuth 2.1 authorization flow with PKCE, so clients like Claude Code will automatically discover the server's authorization endpoint and prompt you to sign in — no manual token copying or configuration required. Once you approve access, the client stores and refreshes credentials automatically.

Clients with known MCP + OAuth 2.1 support include Claude Code CLI, Claude Desktop, Cursor, Windsurf, and Zed. As the MCP ecosystem grows, any new client that follows the OAuth 2.1 MCP spec will work without changes on our end.

How do I connect my ledger?

For clients that support OAuth 2.1 (like Claude Code):

Add the Beancount MCP server URL to your client's MCP configuration.
The client automatically opens a browser window to authorize access.
Log in with your Web Beancount account and pick the ledger you want to grant access to.
Done — the client handles token storage and refresh from here.

For clients without OAuth 2.1 support, generate a static token (scoped to one ledger) from your Web Beancount account settings and pass it as an Authorization: Bearer header.

Is this the same as the "Ask AI" chat feature in the dashboard?

They share the same underlying ledger tools (BQL queries, file read/write), but the MCP server is a different entry point. The dashboard's Ask AI feature is a hosted chat experience with a Cloudflare-backed Claude Code sandbox. The MCP server is a protocol endpoint you connect to from your own AI client of choice — giving you more control, more models, and deeper integration with your existing workflow.

What can the AI actually do with my ledger?

The MCP server exposes four tools:

Tool	What it does
`runBqlQuery`	Execute BQL (Beancount Query Language) to query balances, transactions, accounts
`listLedgerFiles`	Browse the directory structure of your ledger repository
`readLedgerFiles`	Read the contents of `.beancount` files and other ledger documents
`editLedgerFiles`	Create, update, replace, or delete files in an atomic git commit

The AI can combine these: discover your file structure, read relevant files for context, write a BQL query to answer your question, or propose and commit an edit.

Can the AI modify my ledger without me knowing?

File edits require the AI client to call editLedgerFiles with a description of what it's changing. Well-behaved MCP clients (including Claude Code) surface this to you before executing. Edits also support a dry_run mode that previews the exact changes without writing anything, so your client can show you a diff first. And every committed change is a real git commit in your ledger's repository, so you have a full audit trail and can revert anything 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 is returned as structured results to your AI client. The AI model you use (for example, Claude) receives the tool results like any other context. No data is stored by the MCP server beyond what your AI client's conversation already holds.

Each token is ledger-scoped — what does that mean?

When you authorize the MCP server, you choose which ledger to grant access to. That session can only access that ledger. If you have multiple ledgers, you authorize separate sessions. This limits blast radius: a session for your personal ledger cannot touch your business ledger.

Does the MCP server require the Fava web UI to be running?

No. The MCP server talks to the internal Fava API managed by Web Beancount's infrastructure (Fava is the web interface that powers your beancount.io ledger). You don't need to have the Fava UI open or accessible.

What happens if I revoke my MCP access?

Ongoing MCP sessions will receive 401 errors on the next tool call. Clients that support OAuth 2.1 will automatically attempt to re-authorize, prompting you to log in again.

Under the Hood

For the technically curious — how the server is built.

Why MCP over building our own API/plugin per AI tool?

MCP is the emerging standard and already supported by all major AI editors. Building one compliant MCP server gives us compatibility with the whole ecosystem at once, versus maintaining separate integrations for Claude, Cursor, Windsurf, and whatever ships next quarter. The protocol handles discovery, tool schemas, and streaming — we focus on the domain logic.

Why OAuth 2.1 instead of static API keys?

OAuth 2.1 with PKCE is what the MCP specification recommends for remote servers, and it's what clients like Claude Code implement natively. The practical benefit: users never touch a token. The client discovers the authorization server via our .well-known/oauth-protected-resource metadata endpoint, completes PKCE, and manages refresh automatically. Static tokens remain supported as a fallback for clients that haven't implemented the full flow.

Why Streamable HTTP instead of SSE or stdio transport?

Streamable HTTP is the MCP transport designed for remote servers over HTTPS. Stdio is for local processes. SSE (the older MCP transport) is being deprecated in favor of Streamable HTTP. Our users connect from AI clients that are not co-located with our server, so Streamable HTTP is the correct and forward-looking choice.

Why is the MCP session stateless (no sessionIdGenerator)?

We set sessionIdGenerator: undefined to make each request fully stateless — no server-side session state is allocated or retained between tool calls. This matches the Streamable HTTP spec's stateless mode and keeps the server horizontally scalable without session affinity. The tool context (ledger identity, Fava API client) is reconstructed per request from the validated OIDC token.

How does ledger access verification work?

After OIDC token validation, resolveLedgerAccess checks via the Fava API that the authenticated user actually has access to the requested ledger. This prevents a valid token for one ledger from being used to probe another user's ledger (defense-in-depth on top of the signed token).

Where does editLedgerFiles commit to?

It calls changeLedgerFiles on the Fava API, which creates a git commit in the ledger's Gitea repository with the message AI edit: <description>. The description comes from the description field the AI fills in — surfaced to the user in well-behaved MCP clients before execution.

What is the dry_run option on editLedgerFiles?

dry_run: true validates all file operations (checks files exist, verifies str_replace old strings match exactly once) and returns a preview of what would be committed — without actually writing to git. This is useful for AI clients that want to show a diff to the user before committing.

What's the error surface visible to AI clients?

Tool errors are returned as { isError: true, content: [{ type: "text", text: "..." }] } — the MCP SDK's structured error format. The AI client receives the error message as text and can decide how to handle it (retry, report to user, etc.). HTTP-level auth failures (401) include a WWW-Authenticate header pointing to the OAuth protected resource metadata, so compliant clients can automatically re-initiate the authorization flow.