# Expense Tracker MCP Server

A Model Context Protocol (MCP) server for tracking personal expenses and wallet balance, built with [FastMCP](https://github.com/jlowin/fastmcp) and SQLite. Lets Claude Desktop, Cursor, or any MCP client log expenses, summarize spending, and check your balance through natural conversation.

## Features

- Log expenses with date, amount, category, subcategory, and note
- List expenses within a date range
- Summarize spending by category over a date range
- Track and update a wallet balance
- A predefined category/subcategory taxonomy exposed as an MCP resource

## Tools

| Tool | Description |
|------|-------------|
| `add_expense(date, amount, category, subcategory, note)` | Insert an expense record |
| `list_expenses(start_date, end_date)` | List expenses in an inclusive date range |
| `summarize(start_date, end_date, category)` | Sum expenses by category over a date range |
| `get_balance()` | Read the current wallet balance |
| `set_balance(amount)` | Set the wallet balance |

All dates use `YYYY-MM-DD` format and are validated on input.

## Resources

- `expense://categories`: JSON taxonomy of categories and subcategories (food, transport, housing, utilities, health, education, and more), read fresh from `categories.json` on every request.

## Setup

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
```

### Claude Desktop config

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "/path/to/expense-tracker-mcp-server/run.sh"
    }
  }
}
```

Replace `/path/to/expense-tracker-mcp-server` with the absolute path to this repo.

## Storage

Data is stored in a local SQLite database (`expenses.db`, created automatically on first run, gitignored). Override the location with the `EXPENSE_TRACKER_DB_PATH` environment variable.

## Testing

```bash
uv run pytest
```

## License

MIT