FinLedger

A local financial ledger with three read surfaces, plus an MCP server so an agent can query them:

• expenses: spending accounts, reconciled against peer reimbursements

• investments: brokerage balances, holdings, and activity

• income: payroll (gross, withholdings, take-home)

Expenses and investments share a store and nothing else. An account carries an explicit domain, and every expense query joins through it, so a share purchase cannot reach the reimbursement matcher.

The matcher is rules-first. It abstains when it is not sure. A human or agent confirms before a match shrinks net spend.

Real transactions, paystubs, and API keys stay on your machine (~/.finledger/ledger.db, .env). This repository ships code and a synthetic eval set only.

Install

Python 3.10+. The ledger, matcher, MCP loop, and eval harness are standard library. pypdf is optional and only needed to import paystub PDFs.

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

MCP server

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18 tools, namespaced expenses_*, investments_*, and income_*, plus savings_rate, accounts, sync, and reconcile.

Cursor example (~/.cursor/mcp.json):

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

The default ledger path is ~/.finledger/ledger.db.

CLI

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve opens a local desk on :8770. On macOS you can also double-click scripts/Expense Desk.command.

Optional live sources (put credentials in .env, never commit it):

Copy .env.example to .env.

Public eval

The published gold set is synthetic. It is generated by scripts/make_sample_data.py and lives in data-sample/. Every transaction row is marked synthetic: true. It is a coverage set for matcher behaviours (clean match, fan-in, bundling, peer-outbound parent, merchant credits, weak notes, cross-source twins). It is not anonymized real data.

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

Numbers you can reproduce from this repo

Measured on data-sample/ with rules_v0 (window ±90 days, auto-match threshold 0.75):

Re-run python3 scripts/eval_public.py to refresh these. Two remaining false positives on the sample are real matcher weaknesses, including the emoji recall-lift rule overreaching.

What is not in this repo

A private gold set of about 92 labeled examples was used during development. It names real people and real purchases and is not published. Do not treat the sample numbers as a reproduction of that set. Different corpus, different size, different scores.

This repository does not claim 100% auto-match precision.

Matcher

See reconcile/README.md. Short version:

Label the sample corpus with python3 labeling/app.py (defaults to data-sample/).

License

MIT