# Expense Tracker MCP Server

A lightweight local MCP (Model Context Protocol) server that lets you log, list, summarize, and remove personal expenses directly through Claude — no app, no manual spreadsheet entry, just natural conversation.

Built with [FastMCP](https://github.com/jlowin/fastmcp) and backed by a local SQLite database.

## Why

Most expense-tracking apps are clunky: too many taps, rigid categories, or subscription paywalls just to log a coffee. This server turns Claude into your expense tracker — you just tell it what you spent, and it's saved. Ask for a summary anytime and get an instant breakdown by category.

## Features

- **Add expenses** with date, category, amount, subcategory, and notes
- **List expenses** within a date range
- **Summarize spending** by category (optionally filtered to one category)
- **Remove expenses** by ID
- Data stored locally in a single SQLite file — fully private, no cloud sync

## Requirements

- Python 3.10+
- [`fastmcp`](https://pypi.org/project/fastmcp/)

Install dependencies:

```bash
pip install fastmcp
```

## Setup

1. Save the server script (e.g. `expense_server.py`) somewhere permanent on your machine.
2. On first run, it automatically creates `expenses.db` in the same directory — no manual DB setup needed.
3. Add it to your Claude Desktop config file:

   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

   ```json
   {
     "mcpServers": {
       "expense-tracker": {
         "command": "python",
         "args": ["/full/absolute/path/to/expense_server.py"]
       }
     }
   }
   ```

   Use the **absolute path** to the script. If you're using a virtual environment, point `command` to that environment's Python binary instead of system `python`.

4. Restart Claude Desktop. The four tools below should appear as available.

## Tools

| Tool | Description | Parameters |
|---|---|---|
| `add_expense` | Adds a new expense | `date`, `category`, `amount`, `subcategory` (optional), `note` (optional) |
| `list_expenses` | Lists expenses in a date range | `start_date`, `end_date` |
| `summarize_expenses` | Totals spending by category in a date range | `start_date`, `end_date`, `category` (optional) |
| `remove_expense` | Deletes an expense by ID | `expense_id` |

Dates should be in `YYYY-MM-DD` format.

## Example usage

Just talk to Claude naturally once the server is connected:

- "Log 450 for groceries today, subcategory vegetables"
- "I spent 1200 on rent yesterday, note: August rent"
- "Show me everything I spent this month"
- "What's my breakdown by category for August 2026?"
- "How much did I spend on food between Aug 1 and Aug 15?"
- "Delete expense #12, I entered that twice"

## Data storage

All data lives in `expenses.db`, a SQLite file created next to the script. Nothing is sent anywhere else — this is entirely local and private.

**Schema:**

```
expenses
├── id            INTEGER PRIMARY KEY AUTOINCREMENT
├── date          TEXT NOT NULL
├── category      TEXT NOT NULL
├── amount        REAL NOT NULL
├── subcategory   TEXT DEFAULT ''
└── note          TEXT DEFAULT ''
```

## Backing up your data

Since everything lives in one file, back it up periodically:

```bash
cp expenses.db "expenses_backup_$(date +%Y%m%d).db"
```

Consider automating this with a weekly cron job (macOS/Linux) or Task Scheduler (Windows).

## Notes & tips

- Category names aren't constrained, so try to keep casing/spelling consistent (e.g. always "Groceries", not a mix of "groceries" / "Grocery") to keep summaries clean.
- Ask Claude to list your existing categories before adding a new one if you want to avoid duplicates.
- This server has no authentication or network exposure — it only runs locally via stdio, which is why it's safe to use without extra security setup.

## License

Personal use — adapt freely for your own workflow.