ledgerline
Local-first personal finance pipeline: SQLite ledger, bank-export ingest, recurring-payment detection, and read-only MCP tools for AI agents
Install / Use
claude mcp add jeraldhu-yuan -- npx -y github:jeraldhu-yuan/ledgerlineIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
Our assessment of ledgerline
ledgerline scores 70/100 on our quality scale, 2579th of 2,760 Automation skills we index.
Its MCP Server is 11 KB long, well organised into 20 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated about 5 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 90/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
ledgerline compared with similar skills
All 4 of these similar skills score higher than ledgerline; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| ledgerline (this skill)by jeraldhu-yuan | 70 | 3 | 5mo ago | MCP Server |
| claude-memby thedotmack | 100 | 118.0k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.8k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install ledgerline?
- Run
claude mcp add jeraldhu-yuan -- npx -y github:jeraldhu-yuan/ledgerline. The install tabs above show the steps for each supported agent. - Which AI agents does ledgerline work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is ledgerline safe to use?
- It is MIT-licensed and scores 90/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is ledgerline still maintained?
- The repository was last updated about 5 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubledgerline
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.

Try it in 90 seconds
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 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.)
Quick start with real data
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 (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.
AI agent access (recommended)
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?"
Setting up via an AI agent
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
connectand 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, anddemoprints the exactcodex mcp add/claude mcp addcommands to wire up the MCP server. When registering, pick a server name that doesn't collide with one the user already has.
Usage
# 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.
Contributing a bank profile
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. 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 for the pattern.
Idempotency
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_idwith 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).
Security invariants
data/,*.db,*.csv,*.ofx,*.qfx,.env,analysis/, and*.ipynbgitignored from the first commit; test fixtures anddemodata 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 intests/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=roURI), 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_URLor a0600config file only — never the repo, the DB, or the LLM context.httpsis 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_KEYfrom env only; LLM steps fail loudly without it, everything else runs keyless.
Tests
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.
License
MIT — see LICENSE.
Related Skills
claude-mem
118.0kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.8kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
