# Expense Tracker MCP Server

An MCP server for tracking expenses with a small SQLite-backed data store and a built-in categories resource.

## What it provides

- `add_expense`: insert a new expense record.
- `list_expenses`: list expenses in an inclusive date range.
- `summarize`: aggregate spending by category for a date range, with an optional category filter.
- `expense:///categories`: expose the category list as JSON.

## Storage

The server stores data in a SQLite database inside the operating system temporary directory:

- Database file: `expenses.db`
- Location: the current temp folder returned by Python's `tempfile.gettempdir()`

On startup, the server creates the `expenses` table if it does not already exist and performs a small write test to confirm the database is writable.

## Categories

If `src/expense_tracker_mcp_server/categories.json` exists, the server serves that file content through `expense:///categories`.

If the file is missing, it falls back to these default categories:

- Food & Dining
- Transportation
- Shopping
- Entertainment
- Bills & Utilities
- Healthcare
- Travel
- Education
- Business
- Other

## Requirements

- Python 3.14 or later
- `fastmcp`
- `aiosqlite`

## Run the server

From the project root:

```bash
python src/expense_tracker_mcp_server/main.py
```

The server starts an HTTP transport on `0.0.0.0:8000`.

## Tool reference

### `add_expense`

Adds a new expense entry.

Arguments:

- `date`: expense date as text
- `amount`: numeric amount
- `category`: top-level category name
- `subcategory`: optional subcategory text
- `note`: optional note text

Returns:

- `status`
- `id` on success
- `message`

### `list_expenses`

Lists expenses whose `date` value falls between `start_date` and `end_date`, inclusive.

Arguments:

- `start_date`
- `end_date`

Returns a list of expense objects ordered by newest date first, then by descending id.

### `summarize`

Summarizes expenses by category for a date range.

Arguments:

- `start_date`
- `end_date`
- `category` optional filter

Returns totals grouped by category, including sum of amount and count.

## Notes

- The server currently uses a temporary SQLite database, so data is not meant to be permanent.
- The module is implemented in [src/expense_tracker_mcp_server/main.py](src/expense_tracker_mcp_server/main.py).