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 Python (if you haven't already)

finn-tracker requires Python 3.9 or later. Check if you have it:

python3 --version

If you see Python 3.9 or higher, skip to Step 2. Otherwise, install it:

• macOS: Download from python.org or run brew install python
• Ubuntu/Debian: sudo apt install python3

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:

pip install finn-tracker

Tip: If pip isn't found, try pip3 install finn-tracker or python3 -m pip install finn-tracker.

Optional — use a virtual environment: If you want to keep finn-tracker isolated from other Python packages, create a virtual environment first:

python3 -m venv ~/.venvs/finn-tracker
source ~/.venvs/finn-tracker/bin/activate
pip install finn-tracker

You'll need to activate the environment (source ~/.venvs/finn-tracker/bin/activate) each time before running finn-tracker.

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 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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 (checking), Chase Credit, Bank of America, Capital One, generic
PDF	Capital One, Chase, Bank of America (Visa Signature), 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.

For performance optimization guidance when scaling beyond 10K transactions, see SCALING.md.

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