# Expense Tracker MCP

A personal expense tracking server built with [FastMCP](https://github.com/jlowin/fastmcp) that exposes tools and resources via the Model Context Protocol (MCP). Connect it to any MCP-compatible AI client (Claude Desktop, Cursor, etc.) to log, query, and summarize your spending through natural language.

## Features

- **Add expenses** — record date, amount, category, optional subcategory, and a free-text note
- **List expenses** — retrieve all entries within any date range
- **Summarize spending** — aggregate totals by category, optionally filtered to a single category
- **Category reference** — a live-reloadable resource (`expense://categories`) exposes all valid categories and subcategories so the AI always suggests valid values

## Tech Stack

| Component | Technology |
|-----------|------------|
| MCP framework | [FastMCP](https://github.com/jlowin/fastmcp) ≥ 3.1 |
| Database | SQLite (file-based, zero config) |
| Runtime | Python ≥ 3.12 |

## Project Structure

```
expense-tracker-mcp/
├── main.py            # MCP server — tools & resource definitions
├── categories.json    # Category / subcategory taxonomy (editable at runtime)
├── expenses.db        # SQLite database (auto-created on first run)
├── pyproject.toml     # Project metadata & dependencies
└── README.md
```

## Getting Started

### 1. Clone and install dependencies

```bash
git clone <repo-url>
cd expense-tracker-mcp

uv sync
```

### 2. Run the server

```bash
uv run python main.py
```

The server starts and listens for MCP connections. The `expenses.db` SQLite file is created automatically next to `main.py` on the first run.

### 3. Connect to an MCP client

#### Claude Desktop

Add the following block to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/expense-tracker-mcp", "python", "main.py"]
    }
  }
}
```

#### Cursor / other clients

Follow your client's MCP configuration guide, pointing the command at the same Python executable and `main.py`.

## MCP Tools

### `add_expense`

Add a new expense entry.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | `string` | Yes | ISO 8601 date, e.g. `2026-03-09` |
| `amount` | `number` | Yes | Expense amount (positive value) |
| `category` | `string` | Yes | Top-level category (see categories below) |
| `subcategory` | `string` | No | Subcategory within the category |
| `note` | `string` | No | Free-text description |

**Returns:** `{ "status": "ok", "id": <inserted row id> }`

---

### `list_expenses`

Retrieve all expenses within a date range (inclusive).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `start_date` | `string` | Yes | ISO 8601 start date |
| `end_date` | `string` | Yes | ISO 8601 end date |

**Returns:** Array of expense objects with fields `id`, `date`, `amount`, `category`, `subcategory`, `note`.

---

### `summarize`

Aggregate total spending by category within a date range.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `start_date` | `string` | Yes | ISO 8601 start date |
| `end_date` | `string` | Yes | ISO 8601 end date |
| `category` | `string` | No | Filter to a single category |

**Returns:** Array of `{ "category": "...", "total_amount": <number> }` objects, ordered alphabetically.

## MCP Resource

### `expense://categories`

Returns the full `categories.json` file as `application/json`. The file is read from disk on every request, so you can add or rename categories without restarting the server. The AI uses this resource to suggest valid category and subcategory values when logging expenses.

## Categories

The taxonomy ships with 18 top-level categories:

| Category | Example Subcategories |
|----------|-----------------------|
| `food` | groceries, dining_out, delivery_fees |
| `transport` | fuel, public_transport, cab_ride_hailing |
| `housing` | rent, repairs_service, furnishing |
| `utilities` | electricity, internet_broadband, mobile_phone |
| `health` | medicines, doctor_consultation, fitness_gym |
| `education` | books, courses, online_subscriptions |
| `family_kids` | school_fees, daycare, toys_games |
| `entertainment` | movies_events, streaming_subscriptions, games_apps |
| `shopping` | clothing, electronics_gadgets, home_decor |
| `subscriptions` | saas_tools, cloud_ai, music_video |
| `personal_care` | salon_spa, grooming, cosmetics |
| `gifts_donations` | gifts_personal, charity_donation, festivals |
| `finance_fees` | bank_charges, interest, brokerage |
| `business` | hosting_domains, marketing_ads, contractor_payments |
| `travel` | flights, hotels, visa_passport |
| `home` | household_supplies, cleaning_supplies, small_repairs |
| `pet` | food, vet, grooming |
| `taxes` | income_tax, gst, filing_fees |

Every category also accepts `"other"` as a catch-all subcategory. Edit `categories.json` freely to add your own.

## Example Prompts

Once connected to an AI client:

```
Add an expense: ₹450 on groceries today
```

```
List all my expenses for February 2026
```

```
Summarize my spending between 2026-01-01 and 2026-03-09
```

```
How much did I spend on food and transport this month?
```

## Development

### Inspect with MCP Inspector

FastMCP 3.x ships with an interactive inspector. Launch it with:

```bash
uv run fastmcp dev inspector main.py
```

This opens the MCP Inspector UI in your browser so you can call tools and browse resources interactively without a full AI client.

### Reset the database

The schema is initialised automatically via `init_db()` on first run. To wipe all data:

```bash
rm expenses.db
```