runBqlQuery
Run BQL (Beancount Query Language) queries against balances, transactions, and accounts
LABSCO SUMMARY
dry_run on the one write tool is the difference between an agent that can help with your books and one that can damage them.
Plain-text accounting is appealing precisely because every change is a diff, and this server keeps that property: edits land as one atomic commit, and the agent can preview exactly what that commit would be before making it. Wire the dry run into your workflow and the model's mistakes stay hypothetical. The scoping matters too: at sign-in you choose whether a connection reaches one ledger or all of them, so approve only the books the agent needs.
What it is
Beancount.io's hosted server over your ledger repositories. The ledger tools query with BQL, read files and write changes as a single git commit; further tools manage API keys and stage bank imports.
What you get
- runBqlQuery — Beancount Query Language against balances, transactions and accounts
- listLedgers — the ledgers the connection may reach, so one server covers every book
- listLedgerFiles and readLedgerFiles — browse the repository and read the .beancount files
- editLedgerFiles — create, update, replace or delete in one atomic git commit, with a dry_run mode that validates and previews the exact change first
- API keys — list, mint and revoke; minting needs a paid plan and an OAuth sign-in rather than a key
- Bank connections and imports — stage, submit or discard transactions; a new bank is linked in the browser, not over MCP
Requirements
OAuth 2.1 through the browser, where you approve one ledger or all of them; credentials refresh automatically. Clients without OAuth 2.1 use a static token from account settings. The server keeps no session state between calls.
Setup effort
Paste a URL, then authorize — add the endpoint to your client, then approve the OAuth consent screen
USE CASES
01
Answering a question about the books
Run a BQL query over balances and transactions instead of opening the ledger and reading.
02
Adding transactions safely
Preview the edit with dry_run, check the diff, then let it commit atomically.
03
Finding where something is recorded
Browse the repository structure and read the relevant .beancount file directly.
4 tools
Listed in project docs. Your client may show a different list.
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; supports dry_run mode that validates and previews exact changes without writing
BEFORE YOU INSTALL
What to know first
Tools you get
4 tools named in the project's documentation.
Requires
- an MCP client that can reach a remote endpoint
- OAuth 2.1 with ledger-scoped sessions, browser sign-in on first use and automatic refresh, or a static token from account settings
INSTALLATION
Connect your client
Add the endpoint to your client, then approve the OAuth consent screen.
Server setup
ENDPOINT URL
https://beancount.io/api-gateway/mcpRequirements
- OAuth 2.1 with ledger-scoped sessions, browser sign-in on first use and automatic refresh, or a static token from account settings
