Expenses Tracker

A local-first expense tracking app built with FastAPI, SQLite, React, and Vite.

The backend stores transactions in a local SQLite database, serves the API under /api, and serves the built React frontend from the FastAPI app. The project also includes an MCP server for querying and classifying transactions from compatible clients.

Features

• Import bank statement CSV files
• Add, edit, delete, filter, and classify transactions
• Maintain accounts and account groups
• View monthly overview, category totals, and daily reports
• Run a local MCP server with guarded read-only SQL plus transaction classification tools

Project structure

src/expenses_tracker/
  main.py                 FastAPI app entry point
  database.py             SQLite setup and seed accounts
  transactions.py         Transaction data operations
  import_statement.py     CSV statement import logic
  api/routes.py           API routes
  static/                 Built frontend served by FastAPI

src/expenses_tracker_mcp/
  server.py               MCP server for expense tools

frontend/
  index.html              Vite entry HTML
  src/                    React source
  vite.config.js          Builds into src/expenses_tracker/static

data/
  expenses.db             Local SQLite database, ignored by git

Requirements

• Python 3.12+
• uv
• Node.js and npm

Setup

Install Python dependencies:

uv sync

Install frontend dependencies:

cd frontend
npm install

Build the frontend

The FastAPI app serves the compiled frontend from src/expenses_tracker/static.

cd frontend
npm run build

Run the app

uv run expenses

The app starts on http://127.0.0.1:8125 and opens the default browser automatically.

On first startup, the app creates data/expenses.db and seeds the default income statement lines, account groups, and accounts.

Bank statement imports

The transaction screen can import a CSV file through the browser. The backend also supports importing a local statement.csv from the project root when POST /api/import-bank-statement is called without a request body.

Expected CSV columns:

• Transaction Date in DD/MM/YYYY format
• Transaction Description
• Debit Amount
• Credit Amount

Debit amounts are stored as negative pence values. Credit amounts are stored as positive pence values. Imported transactions are assigned to the Pending account by default.

statement.csv is ignored by git because bank statements can contain sensitive financial data.

API overview

• GET /api/health
• GET /api/account-groups
• GET /api/accounts
• POST /api/accounts
• GET /api/transactions
• POST /api/transactions
• PATCH /api/transactions/{transaction_id}
• DELETE /api/transactions/{transaction_id}
• POST /api/import-bank-statement

MCP server

Run the MCP server with:

uv run expenses-mcp

Available tools include:

• guarded read-only SQL queries
• transaction listing with filters
• account listing
• pending transaction grouping
• classification summaries
• account assignment for selected transactions or filtered batches

Use dry-run mode before bulk classification changes.

Development notes

• Frontend source lives in frontend/src.
• Frontend build output is committed under src/expenses_tracker/static so the FastAPI app can serve the UI directly.
• Local runtime data is ignored under data/*.db.
• If dependencies change, commit both pyproject.toml/uv.lock and frontend/package.json/frontend/package-lock.json.