# Personal Finance Tracker MCP Server

An MCP server that lets you log and query your own spending through natural conversation with Claude, instead of a spreadsheet or app.

## What it does

You talk to Claude. Claude calls these tools against your local SQLite database:

| Tool | What it does |
|------|-------------|
| `add_expense` | Log a purchase — amount, category, description, date, source |
| `query_expenses` | Filter expenses by date range and/or category |
| `monthly_summary` | Total spend, breakdown by category, remaining budget |
| `update_expense` | Fix a mis-logged expense by ID |
| `delete_expense` | Remove an expense by ID |
| `search_expenses` | Find expenses by description text |
| `list_categories` | Show all categories you've used |

Monthly cap is set to $2,000 — change `MONTHLY_CAP` in `src/index.ts` to match yours.

## Storage

SQLite, single file (`expenses.db`), zero setup. Schema is in `schema.sql`. The database file is gitignored — your spending data stays local.

## Setup

```bash
npm install
npm run build
```

## Use with Claude Desktop

Add to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "finance-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/finance-tracker-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop. Then just talk to it:

- "I spent $14.50 on lunch today"
- "How much have I spent this month?"
- "Show me all grocery expenses from last week"
- "Delete expense 7"

## Design decisions

- **SQLite over Postgres**: this is a personal, local-only tool. One file, zero infrastructure, easy to back up.
- **Free-text categories**: no fixed enum. Your categories emerge from how you actually talk about spending. `list_categories` shows what you've used so far.
- **Structured dates on the tool interface**: the tool takes ISO dates (`YYYY-MM-DD`), and the model handles the "last week" → date range translation. Keeps parsing logic out of the server.
- **Search tool for ambiguity**: when you say "delete the coffee expense" and there are three, `search_expenses` lets Claude show you the matches and ask which one.

## Build Plan

See [BUILD_PLAN.md](BUILD_PLAN.md) for the phased plan and future ideas (budget alerts, recurring expenses, CSV import, multi-currency).