Show HN: Ledgerline – local-first finance MCP server

Ledgerline, a local-first finance MCP server, gives AI agents read-only access to financial data via a single SQLite file without cloud storage or exposing credentials. The tool supports bank sync through SimpleFIN Bridge and CSV/OFX/QFX file imports, running entirely locally with no API keys required for core functionality.

Give AI agents read-only access to your finances without giving anyone your data: one SQLite file on your machine, no cloud, exact integer-cent answers over MCP. Everything runs locally. Bank access via SimpleFIN Bridge is read-only by construction — Ledgerline never sees your banking credentials and cannot move money. Account numbers are dropped at parse time, so the model can never see what the database never contains. Delete the one .db file and every trace is gone. No clone, no signup, no API key, no real financial data — the demo seeds six months of clearly fabricated transactions so you can evaluate everything before connecting anything. uv https://docs.astral.sh/uv/getting-started/installation/ is the only prerequisite. uvx --from ledgerline ledgerline demo uvx --from ledgerline ledgerline summary income/outflow by category uvx --from ledgerline ledgerline upcoming expected charges, next 30 days demo prints copy-paste one-liners that connect the MCP server to Codex or Claude Code; then ask things like "What recurring charges are coming up?" or "Why was last month so expensive?". When you're done evaluating, delete data/ledgerline.db and start fresh with real data below. demo refuses to write into a database that already has transactions. git clone https://github.com/jeraldhu-yuan/ledgerline cd ledgerline uv sync Then get transactions in. Both paths work, and they can be mixed freely — the importer deduplicates. Bank sync. Sign up at https://bridge.simplefin.org https://bridge.simplefin.org SimpleFIN Bridge, a small paid service that turns your bank logins into read-only transaction feeds — Ledgerline never sees your banking credentials , link your bank s , and create a new app on your account page to get a one-time setup token. Then: uv run ledgerline connect paste the setup token when prompted uv run ledgerline sync pull your transactions connect stores the resulting access URL owner-only in ~/.config/ledgerline/simplefin.env . The first sync prompts to map each bank account to a local label; re-running is always safe, and a stale database catches up in provider-friendly 45-day windows. If an institution is missing from SimpleFIN's catalog, that account just stays on file import — mixing both paths is a supported steady state. File import. Download a CSV/OFX/QFX export from your bank's website: uv run ledgerline ingest export.csv --account "Checking" The database lives at data/ledgerline.db gitignored ; override with --db or LEDGERLINE DB . No API key is needed for any of this — the two optional embedded LLM commands categorize , ask read ANTHROPIC API KEY from the environment, and everything else runs keyless. Ledgerline runs as a local stdio MCP server exposing read-only tools: data freshness, transaction search, spending summaries, period comparisons, account balances, upcoming payments, and constrained SQL — plus a small set of local-metadata writers so the everyday upkeep works from chat: "I just signed up for a $850/month course, track it", "I cancelled Netflix", "that charge is business travel, not dining", "mark this card as business". Your agent does the categorizing too, so no Anthropic API key is needed on the MCP path. Nothing can touch the bank. The contract is deliberately small and uniform — exact integer cents, totals always per currency and never combined, and limitations staleness, uncategorized spend, unknown account purpose reported as data rather than prescriptive workflow text. The reasoning is the client model's job; the server's job is exact, truthful primitives. The one cache-writing tool, refresh data , pulls from SimpleFIN at most once an hour. A refresh that hits provider errors is recorded as an attempt but not a success, and data status discloses the difference. Codex user scope codex mcp add ledgerline --env LEDGERLINE DB=/absolute/path/to/ledgerline.db -- \ uvx --from ledgerline ledgerline-mcp Claude Code user scope claude mcp add ledgerline --scope user --transport stdio \ --env LEDGERLINE DB=/absolute/path/to/ledgerline.db -- \ uvx --from ledgerline ledgerline-mcp From a repo checkout, point the command at /path/to/ledgerline/.venv/bin/ledgerline-mcp instead of uvx . Restart the client, then ask things like "How much did I spend on dining in January?" or "What recurring charges are coming up?" If an AI agent is doing the setup, every step is non-interactive except the ones that belong to the human: Human only: signing up at SimpleFIN Bridge, linking banks, and creating the setup token all happen on SimpleFIN's website with real banking credentials. Never give an agent your bank login; the tool never sees it either.- The human hands the agent only the one-time setup token. Then: ledgerline connect --token "$SETUP TOKEN" claim it, no prompt ledgerline sync --accept-default-labels map new accounts automatically - The setup token is single-use: it is consumed by connect and worthless afterward, so it transiting an agent's context is bounded risk. The resulting access URL is stored owner-only on disk and never enters the model. - The demo path ledgerline demo and file import ledgerline ingest have no prompts at all, and demo prints the exact codex mcp add / claude mcp add commands to wire up the MCP server. When registering, pick a server name that doesn't collide with one the user already has. Monthly summary: income/outflow by category, top merchants, deltas uv run ledgerline summary --month 2026-06 Resolve uncached merchants with ONE batched LLM call uv run ledgerline categorize Confirm/correct categories; corrections apply retroactively uv run ledgerline review Recurring payments uv run ledgerline recurring detect uv run ledgerline recurring add --label "Course tuition installment" \ --amount 850.00 --cadence monthly --day 21 uv run ledgerline upcoming --days 30 Embedded Q&A for use without an MCP client needs ANTHROPIC API KEY uv run ledgerline ask "why was June so expensive?" CSV dump for analysis elsewhere uv run ledgerline export --month 2026-06 --out june.csv Durable account context for agents and reports uv run ledgerline accounts set-context "Chequing" --purpose mixed \ --entity "Northwind Consulting" --business-use-percent 70 \ --context "Business income plus personal spending" Account context personal / business / mixed / unknown , owning entity, business-use percentage, free-form note persists in SQLite and rides along on every MCP result, so agents segment cash flow before judging it. If your bank's CSV doesn't auto-detect, the fix is a ~10-line pull request: add one dict to PROFILES in ledgerline/ingest/profiles.py /jeraldhu-yuan/ledgerline/blob/main/ledgerline/ingest/profiles.py . OFX/QFX needs no profile. "us checking": { "columns": {"date": "Posting Date", "amount": "Amount", "description": "Description"}, "date format": "%m/%d/%Y", "sign": 1, -1 if the export shows charges as positive "skip rows": 0, "external id column": None, column with a bank-side unique id, if any }, Include a small fabricated CSV fixture invented merchants, never real account data in tests/fixtures/ and a test asserting it ingests with the right sign convention — see test sign convention profile in tests/test ingest.py /jeraldhu-yuan/ledgerline/blob/main/tests/test ingest.py for the pattern. Re-importing a file, overlapping export ranges, and sync + file import of the same period all produce zero duplicates tested in tests/test ingest.py and tests/test sync.py . Design note — one deliberate deviation from the spec: the spec folds FITID into dedupe hash when present. Done literally, that would create duplicates in mixed mode: a CSV row no FITID and a SimpleFIN row with id for the same transaction would hash differently. Instead: dedupe hash = sha256 account id | posted date | amount cents | merchant raw | occurrence index with occurrence counting — the Nth identical row in a batch is a duplicate only if the DB already holds more than N such rows. Two genuinely distinct same-day, same-amount, same-merchant transactions survive because they arrive in the same export with occurrence indexes 0 and 1.- Bank-side ids OFX FITID, SimpleFIN txn id are stored in external id with a unique per-account index, short-circuit re-imports, and are backfilled onto rows that originally arrived without one. This satisfies every acceptance test, including both orders of mixed-mode. Caveat: cross-source dedupe matches on the raw description, so it works when both sources export the same description string typical for OFX/SimpleFIN from the same institution . data/ , .db , .csv , .ofx , .qfx , .env , analysis/ , and .ipynb gitignored from the first commit; test fixtures and demo data are fabricated only.- Account numbers are never parsed: the OFX reader and SimpleFIN connector drop ACCTID / BANKID -class fields at parse time. Only short labels "US Checking" identify accounts. Asserted in tests/test security.py . - The model gets full transaction detail through run sql — by design. What it can never see is what the DB never contains: account numbers, credentials, raw export files. run sql : read-only connection mode=ro URI , single-statement SELECT/WITH only, keyword denylist, SQLite authorizer denying everything but reads, 200-row cap, 5-second time limit, statement/result size limits. Literals and comments are stripped before the keyword scan a merchant named "UPDATE" is not a false positive ; the authorizer and read-only mode are the real guards. Tested with hostile inputs.- SimpleFIN access URL from SIMPLEFIN ACCESS URL or a 0600 config file only — never the repo, the DB, or the LLM context. https is required, HTTP redirects are refused credentials are never replayed to another host , and loose file permissions produce a warning. - New database files are created owner-only 0600 . ANTHROPIC API KEY from env only; LLM steps fail loudly without it, everything else runs keyless. uv run pytest The suite covers the acceptance checklist: mixed-mode dedupe in both orders, quarantine of malformed rows, integer-cents math, per-currency reporting, run sql hardening against hostile inputs, recurring detection with gap tolerance, the MCP tools, the demo seeder, and the security invariants above. MIT — see LICENSE /jeraldhu-yuan/ledgerline/blob/main/LICENSE .