Metadata-Version: 2.4
Name: finn-tracker
Version: 0.0.1
Summary: Privacy-first local expense tracker — import bank CSVs/PDFs, auto-categorize, explore trends. No data ever leaves your machine.
License-Expression: MIT
Project-URL: Homepage, https://github.com/RachithP/finn-tracker
Project-URL: Issues, https://github.com/RachithP/finn-tracker/issues
Keywords: finance,expense,privacy,local,csv,pdf
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flask<4,>=3.0
Requires-Dist: pdfplumber<1,>=0.11
Requires-Dist: pandas>=1.5
Requires-Dist: pypdf>=3.0
Requires-Dist: reportlab>=4.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# finn-tracker

[![CI](https://github.com/RachithP/finn-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/RachithP/finn-tracker/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/RachithP/9088e1501976e0528e0da2fa5d38a465/raw/badge.json)](https://github.com/RachithP/finn-tracker/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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](https://github.com/ggerganov/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](https://modelcontextprotocol.io)
- **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:

```bash
python3 --version
```

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

- **macOS**: [Download from python.org](https://python.org/downloads) 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:

```bash
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:
> ```bash
> 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

```bash
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:

```bash
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](https://github.com/ggerganov/llama.cpp). No data is sent to any external service.

**To enable it:**

1. Install and start [llama-server](https://github.com/ggerganov/llama.cpp#quick-start) 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](https://modelcontextprotocol.io) 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`:

```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](CONTRIBUTING.md) for how to get started.

For performance optimization guidance when scaling beyond 10K transactions, see [SCALING.md](SCALING.md).

[Open an issue on GitHub](https://github.com/RachithP/finn-tracker/issues) — include the output of `finn-tracker --version`.
