ledgerline

Purpose

Ledgerline is a local-first personal finance pipeline designed to let AI agents have read-only access to personal financial information without handing data to any third party. It stores all data locally in a SQLite file and does not depend on cloud services.

Main Capabilities

• Bank export import: Supports importing CSV, OFX, and QFX files downloaded from bank websites. The importer automatically deduplicates, supporting repeated imports and overlapping export ranges without producing duplicate records.
• Bank sync: Connects to bank accounts through SimpleFIN Bridge (a paid service) to retrieve a read-only transaction stream. Ledgerline never touches bank credentials and cannot move money. On the first sync, it prompts you to map each bank account to a local label.
• Recurring payment detection: Automatically identifies recurring charges and subscriptions.
• AI agent access (MCP): Runs as a local stdio MCP server, exposing read-only tools, including: data freshness, transaction search, spending summaries, period comparisons, account balances, upcoming payments, and restricted SQL queries. There are also a small number of local metadata write tools that support routine maintenance from chat, for example: "I just signed up for a $850 per month course, track it," "I canceled Netflix," "this expense is a business trip, not dining," "mark this card as business."
• Exact calculations: All amounts use integer cents, are summarized separately by currency, and are never mixed.
• Local metadata: Account context (personal/business/mixed/unknown, owning entity, business use percentage, free-form notes) is persisted in SQLite and passed along with every MCP result.

How to Use

90-second demo

Only install uv. Running ledgerline demo generates six months of fictional transaction data and prints a copy-pasteable one-line command to connect the MCP server to Codex or Claude Code. You can then ask: "What recurring charges are coming up?" or "Why was last month so expensive?" The demo refuses to write to a database that already has transactions. After evaluating, delete data/ledgerline.db to start over.

Real data quick start

1. Bank sync: Sign up for SimpleFIN Bridge at https://bridge.simplefin.org , link your bank, and create a new app on the accounts page to get a one-time setup token. Run ledgerline connect to store the access URL in ~/.config/ledgerline/simplefin.env(readable only by the owner). The first sync will prompt you to map accounts.
2. File import: Download CSV/OFX/QFX export files from your bank's website and run ledgerline ingest <文件>. The database is located at data/ledgerline.db(gitignored), and can be overridden with --db or LEDGERLINE_DB .

No API keys are required. The two optional embedding LLM commands (categorize、ask) read ANTHROPIC_API_KEYfrom the environment; everything else requires no keys.

AI agent access (recommended)

Run the local MCP server. After restarting the client, you can ask: "How much did I spend on dining in January?" or "What recurring charges are coming up?" When running from a code checkout, point the command at /path/to/ledgerline/.venv/bin/ledgerline-mcp instead of uvx.

Setup through an AI agent

Except for human-only steps (SimpleFIN signup, linking a bank, creating a setup token), the other steps can be performed non-interactively. The human only needs to give the one-time setup token to the agent. The token is single-use,connect becomes invalid after. The final access URL exists only on the local disk and never enters the model context.

Use Cases

• Users who want an AI agent to help analyze personal finances but do not want to upload data to the cloud.
• Developers who need a precise, read-only financial query interface for AI agents to use.
• Scenarios where you want to manage transaction records locally, detect subscriptions and recurring charges, and interact with the data through natural language.

Limitations

• Bank synchronization relies on SimpleFIN Bridge (a paid service), and that service must support your bank; unsupported institutions can continue to use file import, and mixed mode is supported.
• The MCP path does not require an Anthropic API key, and the agent performs classification itself; however, the embedded categorize and ask commands require ANTHROPIC_API_KEY。
• refresh_data tool's pull frequency from SimpleFIN is limited to at most once per hour.
• Cross-source deduplication matches raw description strings and is only effective when both sources export the same description (usually the case for OFX/SimpleFIN from the same institution).
• run_sql only allows a single SELECT/WITH statement, with safety limits such as a 200-row cap and a 5-second timeout.
• Account numbers are discarded during parsing and cannot be seen by the model; once the database file is deleted, all traces disappear.

Security Invariants

• Data files (data/、*.db、*.csv、*.ofx、*.qfx、.env、analysis/、*.ipynb) are gitignored from the first commit.
• The OFX reader and SimpleFIN connector discard ACCTID/BANKID -type fields during parsing and identify accounts only with short labels.
• run_sql uses a read-only connection (mode=ro URI), single-statement SELECT/WITH, a keyword blacklist, a SQLite authorizer that denies everything except reads, a 200-row cap, a 5-second time limit, and statement/result size limits. Literals and comments are stripped before keyword scanning.
• The SimpleFIN access URL is read only from an environment variable or a 0600 configuration file, requires HTTPS, and rejects HTTP redirects.
• New database files are created with 0600 permissions.
• ANTHROPIC_API_KEY is read only from environment variables.

Contributing Bank Configurations

If a bank CSV cannot be auto-detected, you can add a dictionary (about 10 lines) to ledgerline/ingest/profiles.py 's PROFILES . OFX/QFX requires no configuration. Please include fictional CSV test fixtures and tests that verify the sign conventions.