# Expense Tracker MCP Server

A Python-based FastMCP server for tracking personal expenses with MongoDB storage and a fixed category/subcategory model.

## Project Overview

This repository implements an expense tracker as an MCP service using `fastmcp`. It stores expenses in a MongoDB collection and enforces a predefined set of categories and subcategories defined in `categories.json`.

The server exposes the following MCP tools:
- `list_categories()`
- `add_expense(amount, category, subcategory, date=None, note=None)`
- `update_expense(expense_id, amount=None, category=None, subcategory=None, date=None, note=None)`
- `delete_expense(expense_id)`
- `list_expenses(start_date=None, end_date=None, category=None, limit=20)`
- `get_expense_summary(start_date=None, end_date=None, group_by="category")`

## Requirements

- Python 3.13 or newer
- MongoDB access via connection URI
- `fastmcp`
- `python-dotenv`
- `pymongo`

## Setup

1. Create and activate a Python virtual environment.
2. Install dependencies:

```bash
pip install -r requirements.txt
```

3. Create a `.env` file at the project root with:

```env
MONGODB_URI=<your-mongodb-uri>
```

4. Run the server:

```bash
python main.py
```

5. The server listens on port `8000` by default and can be overridden with the `PORT` environment variable.

## Configuration

- `main.py` contains the MCP service configuration, database connection logic, and expense CRUD operations.
- `categories.json` defines the allowed categories and subcategories for every expense.
- `render.yaml` defines a Render deployment configuration that installs requirements and starts the service.

## Expense Data Model

Each expense document includes:
- `amount` (float)
- `category` (string)
- `subcategory` (string)
- `date` (stored as a date object)
- `note` (optional string)
- `created_at` (UTC timestamp)

Expense IDs are stored as MongoDB `_id` values and returned as `expense_id` in serialized responses.

## Usage Notes

- Use `list_categories()` before adding or updating an expense so you can choose valid category and subcategory values.
- Dates must be in `YYYY-MM-DD` format when provided.
- `add_expense()` requires a positive amount.
- `update_expense()` only changes the fields you provide.
- `list_expenses()` defaults to the most recent 20 expenses and supports filtering by date range and category.
- `get_expense_summary()` aggregates totals by category or by month.

## Deployment on Render

The included `render.yaml` configures a Python web service:
- `buildCommand`: `pip install -r requirements.txt`
- `startCommand`: `python main.py`
- `MONGODB_URI` is expected from a Render-managed secret named `mongodb_uri`

## Category Guidance

The app uses the category definitions from `categories.json`, so do not invent new categories or subcategories. If you need to verify valid values, call `list_categories()`.