MCP Beancount Tool — Project Documentation
Description
Build an MCP server that integrates with Beancount 3.2.0 to expose safe, structured tools for: viewing accounts, balances, income sheet (income statement), and transactions; inserting new transactions; removing transactions; and answering natural‑language questions via BeanQuery.
Provide deterministic, validated, and auditable interactions with a local Beancount ledger, suitable for MCP‑compatible clients (e.g., IDE agents or chat assistants) operating offline.
Emphasize correctness (balanced postings, type‑checked inputs), safety (file locking, atomic writes, backups), and usability (clear schemas and messages). Each created transaction receives a stable unique identifier to support safe updates/deletions.
Requirements
Functional
List accounts: return name, type, open/close metadata, currencies, and optional tags/commodities.
Balances: compute account and roll‑up balances at a date or over a period; optionally convert using available price data.
Income sheet: produce an income statement (Income/Expenses and net result) for a specified period.
List transactions: filter by date range, account(s), payee, narration, tags, and metadata; include postings and totals.
Insert transaction: accept structured input (date, flag, payee, narration, postings, metadata), enforce balance; assign
txn_id
(UUID) if missing; validate with Beancount before persisting.Remove transaction: delete by
txn_id
(required for deletion); refuse ambiguous deletes; validate resulting ledger.Query (BeanQuery): execute read‑only BeanQuery strings and return typed rows/columns.
Natural‑language Q&A: map NL questions to safe BeanQuery templates (read‑only); return results and the generated query for transparency.
Dry‑run mode for mutations to preview effects without writing.
Non‑functional
Local‑first and offline; no network dependencies during normal operation.
Performance targets appropriate for 100k+ postings; avoid re‑parsing on trivial reads when possible.
Deterministic output formats and stable ordering for repeatability.
Clear, actionable errors (parse issues, validation failures, unbalanced postings, ambiguous matches).
Strong auditability: atomic writes, automatic timestamped backups, and file locking to prevent concurrent corruption.
Technical
Beancount 3.2.0 for parsing, validation, and query (
beancount.loader
,beancount.core.*
,beancount.query
).Language/runtime: Python 3.11+.
MCP server SDK (Python) using the latest
modelcontextprotocol/python-sdk
; expose tools with JSON‑schema input/output; define stable tool names and schemas.Transport: HTTP transport from the MCP Python SDK (server runs over HTTP).
Testing:
pytest
; sample fixture ledgers; golden files for tool responses where applicable.Cross‑platform file locking and atomic replace on write; UTF‑8 encoding.
Configuration via file and environment: main ledger path, default currency, price/commodities options, locale/timezone.
Security & Privacy
Operate only on configured ledger roots; reject path traversal/out‑of‑scope files.
Sanitize and bound NL→BeanQuery generation to read‑only, parameterized templates; never perform writes from NL intents.
Never transmit ledger data over network; logs must redact sensitive fields when necessary.
Tasks
Project scaffolding
Initialize Python project with
uv
, dependency pins (Beancount 3.2.0), and basic packaging.Add configuration loader (env + config file) for ledger path and options.
Set up
pytest
with sample fixture ledgers for repeatable tests.Provide a minimal example ledger at
tests/fixtures/example.beancount
for testing.
MCP server foundation
Integrate the latest
modelcontextprotocol/python-sdk
.Use HTTP transport for the server; document default port and configuration.
Scaffold server entrypoint and lifecycle (no business logic yet).
Define tool manifests with JSON schemas for inputs/outputs and consistent error models.
Ledger loading & validation
Implement loader using
beancount.loader
with include handling, cache, and diagnostics capture.Provide a validation layer to surface Beancount errors/warnings in a structured form.
Read‑only tools
list_accounts
: enumerate accounts with metadata and inferred types.balance
: compute balances at date/period; include options for cost/value and conversions when price data exists.income_sheet
: generate period income statement (Income, Expenses, Net) with grouping and totals.list_transactions
: filters (date/account/payee/tag/metadata) and pagination; include postings.query
: execute BeanQuery safely; return columns + typed rows.
Mutation tools
insert_transaction
: define input schema; normalize/validate postings; auto‑assigntxn_id
; pretty‑format; atomic write with backup; re‑load to verify.remove_transaction
: requiretxn_id
; locate uniquely; remove; atomic write; re‑load to verify.Introduce optional
dry_run
flag for both mutations; return proposed diff.
Natural‑language layer
Implement a rule/template‑based NL→BeanQuery mapper for common intents (balances, spending by category, income by month, etc.).
Validate generated queries as read‑only; expose the final query in responses for transparency.
Reliability & UX
Add file locking, atomic replace, and timestamped backups; configurable backup retention.
Normalize amounts/commodities and present deterministic output ordering.
Structured, user‑facing error messages with remediation hints.
Testing & examples
Unit tests for each tool, including edge cases (unbalanced inserts, ambiguous deletes, parse errors).
End‑to‑end tests against fixture ledgers and golden responses.
Example configuration and sample queries in docs.
Packaging & release
Package as a Python distribution; pin dependencies; provide entrypoint for MCP server.
Versioning and changelog; minimal quickstart documentation for MCP clients.
MCP SDK & Transport
SDK: Use the latest
modelcontextprotocol/python-sdk
(installed asmodelcontextprotocol
).Transport: HTTP transport. The server will expose an HTTP endpoint for MCP clients; default host/port and CORS/security considerations will be documented alongside configuration. No stdio transport is planned for the default setup.
Development (uv)
Create and sync the environment:
uv sync
(installs project and dev dependencies)
Run tests:
uv run -m pytest
Lint (if desired):
uv run ruff check .
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables interaction with local Beancount accounting ledgers through structured tools for viewing accounts, balances, and transactions, as well as inserting/removing transactions and answering natural-language questions via BeanQuery. Provides deterministic, validated, and auditable financial data operations with offline-first functionality.