finn-tracker

A fully local expense tracking and visualization tool. Import bank CSVs and PDF statements, auto-categorize transactions, and explore spending trends through an interactive dashboard. No data ever leaves your machine.

---

Features

• Auto-import — drop CSVs/PDFs into ~/Documents/finn-tracker/expense/ (or income/) and they load automatically on every page refresh (set EXPENSE_TRACKER_DATA=/your/path to use a different directory)
• Smart categorization — 200+ static rules auto-categorize merchants across 15 categories (including Donations); manual overrides are persisted, learned as reusable rules, and applied on future transactions
• Interactive dashboard — summary cards, spending-by-category bar chart, account donut chart, spending trend timeline, and category drill-down
• Period filtering — 1M, 3M, 6M, YTD, This Month, Last Month, All, or a custom date range
• Export — CSV or PDF report with masked merchant names
• AI chat assistant — ask questions about your spending in plain English ("How much did I spend on food last month?"). Powered by a local LLM (llama.cpp) — your data never leaves your machine
• MCP server — connect Claude Desktop, Cursor, Kiro, and other AI tools directly to your expense data via the Model Context Protocol
• Privacy-first — server binds to 127.0.0.1 only; all state stored in a local SQLite DB; sensitive strings masked before any API response

---

Quick Start

Step 1 — Install uv (if you haven't already)

finn-tracker is installed with uv, a fast Python package manager that fetches Python for you if needed — see the uv installation docs for the one-line install.

Note: finn-tracker is developed and tested on macOS and Ubuntu. It may work on other platforms but is not officially supported on Windows.

Step 2 — Install finn-tracker

Open a terminal and run:

uv tool install finn-tracker

Like pipx, uv tool install creates a dedicated environment for finn-tracker in uv's own directory (not in your project or shell) and puts the finn-tracker command on your PATH — nothing to create or activate yourself. (Contributors hacking on the source use a repo-local .venv instead — see CONTRIBUTING.md.)

Prefer plain pip? pip install finn-tracker (Python 3.9+) works too.

Step 3 — Launch

finn-tracker

Your browser opens automatically at http://localhost:5050.

Step 4 — Add your bank statements

Drop your bank CSV or PDF exports into:

~/Documents/finn-tracker/expense/   ← charges, debits
~/Documents/finn-tracker/income/    ← salary, deposits

Then refresh the page — your transactions appear automatically.

Not sure where to find those folders?

• macOS: Open Finder, press ⌘ Shift H to go to your home folder, then open Documents → finn-tracker.
• Ubuntu: Open your file manager and navigate to ~/Documents/finn-tracker/.

---

Try it first with sample data

Not ready to import real statements yet? Run this to load synthetic demo data:

finn-tracker --demo

---

Privacy Guarantee

No data leaves your machine. finn-tracker:

• Runs at 127.0.0.1:5050 — not accessible from the network by default
• Stores everything in SQLite on your disk (~/Documents/finn-tracker/finn_tracker.db)
• Never makes outbound network calls
• Deletes uploaded files immediately after parsing
• Masks card numbers, SSNs, and account numbers in all API responses

---

AI Chat Assistant

finn-tracker includes a built-in chat assistant that answers questions about your spending in plain English:

"How much did I spend on groceries last month?" "What's my biggest expense category this year?" "Show me my top 5 merchants" "Filter the dashboard to last month" "Which transactions are uncategorized?"

The assistant can answer spending questions and control the dashboard — filtering by period or category on your behalf. It runs entirely on your machine using llama.cpp. No data is sent to any external service.

To enable it:

1. Install and start llama-server on port 8080 (the default)
2. Launch finn-tracker — the chat button in the top-right corner will show AI Ready

To use a different port: LLAMA_CPP_URL=http://localhost:8081 finn-tracker

---

MCP Server (Claude Desktop, Cursor, Kiro)

finn-tracker ships an MCP server that lets AI tools query your expense data directly — no browser required.

To connect Claude Desktop:

Add this to your Claude config:

{
  "mcpServers": {
    "finn-tracker": {
      "command": "/path/to/your/python",
      "args": ["/path/to/finn-tracker/mcp_server.py"]
    }
  }
}

Once connected, you can ask Claude things like "summarize my spending this month" or "what did I spend on dining last quarter" directly in Claude Desktop.

---

Supported File Formats

Format	Auto-detected banks
CSV	Chase Bank, Chase Credit, Bank of America, Capital One, generic
PDF	Capital One, Chase, Bank of America, and any table-based statement (pdfplumber)

---

How It Works

1. Files in your expense/income folders are scanned on every page load; unchanged files are cached in memory and not re-parsed.
2. Manually imported files are parsed once and persisted to SQLite.
3. All transactions are deduplicated by (date, merchant, amount, account).
4. Category overrides and learned merchant rules survive server restarts via SQLite.

When you manually categorize a transaction, the app saves a normalized merchant pattern as a rule. Future transactions matching that pattern are auto-categorized.

Use 🗑 Clear Session to undo a bad import without losing your history. Use 🗑 Clear All to start completely fresh.

---

Platform Support

finn-tracker is developed and tested on macOS and Ubuntu. CI runs on both platforms across Python 3.9, 3.11, and 3.12. Other Unix-like systems should work but are not officially tested. Windows is not supported.

---

Contributing

Found a bug or want to add a bank parser? See CONTRIBUTING.md for how to get started.

Open an issue on GitHub — include the output of finn-tracker --version.