# Expense Tracker MCP

A Model Context Protocol (MCP) server for tracking expenses with SQLite persistence.

## Installation

### Prerequisites

- Python 3.13 or higher
- Node.js (for MCP Inspector)
- uv (Python package manager)

### Setup

1. Create a virtual environment:
```bash
python -m venv venv
```

2. Activate the virtual environment:
```powershell
.\venv\Scripts\Activate.ps1
```

3. Install uv:
```bash
pip install uv
```

4. Initialize the project:
```bash
uv init .
```

5. Install dependencies:
```bash
uv add fastmcp --active
```

## Usage

### Running the MCP Server

To run the MCP server:
```bash
uv run main.py
```

The server will automatically create a SQLite database (`expenses.db`) in the project root on first run.

### Testing with MCP Inspector

To test the server using the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector uv run main.py
```

This will start the MCP Inspector web interface at `http://127.0.0.1:6274`.

## Available Resources

The MCP server provides the following resources:

### `expense://categories`
Returns the predefined expense categories and their sub-categories.

**Categories available:**
- **Food**: Groceries, Restaurant, Coffee, Vegetables, Snacks
- **Health**: Pharmacy, Doctor, Fitness, Insurance
- **Entertainment**: Streaming, Movies, Games, Events
- **Transport**: Metro, Auto, Taxi, Fuel, Bus
- **Shopping**: Clothing, Electronics, Home, Gifts
- **Utilities**: Electricity, Internet, Water, Gas, Phone

This resource can be used to get the valid categories and sub-categories for expense tracking.

## Available Tools

The MCP server provides the following tools for expense management:

### `add_expense`
Add a new expense record to the database.

**Parameters:**
- `amount` (float): The amount spent
- `category` (str): The expense category (e.g., "Food", "Transport")
- `date` (str, optional): The expense date as YYYY-MM-DD. Defaults to today
- `sub_category` (str, optional): An optional sub-category (e.g., "Groceries")
- `note` (str, optional): An optional free-text note

**Returns:** The newly created expense record with its assigned ID

### `list_expenses`
List expense records with optional filtering.

**Parameters:**
- `start_date` (str, optional): Only include expenses on or after this date (YYYY-MM-DD)
- `end_date` (str, optional): Only include expenses on or before this date (YYYY-MM-DD)
- `category` (str, optional): Only include expenses matching this category exactly
- `sub_category` (str, optional): Only include expenses matching this sub-category exactly
- `limit` (int, optional): Maximum number of records to return, most recent first

**Returns:** A list of matching expense records

### `edit_expense`
Edit an existing expense record. Only provided fields are updated.

**Parameters:**
- `expense_id` (int): The ID of the expense to edit
- `date` (str, optional): New date as YYYY-MM-DD
- `amount` (float, optional): New amount
- `category` (str, optional): New category
- `sub_category` (str, optional): New sub-category
- `note` (str, optional): New note

**Returns:** The updated expense record

### `delete_expense`
Delete an expense record by ID.

**Parameters:**
- `expense_id` (int): The ID of the expense to delete

**Returns:** A confirmation dict with the deleted ID

### `summarize_expenses`
Summarize expenses with totals, optionally filtered and grouped.

**Parameters:**
- `start_date` (str, optional): Only include expenses on or after this date (YYYY-MM-DD)
- `end_date` (str, optional): Only include expenses on or before this date (YYYY-MM-DD)
- `category` (str, optional): Only include expenses matching this category exactly
- `group_by` (str): How to group the breakdown: "category", "sub_category", or "date". Defaults to "category"

**Returns:** A dict with overall total, count of matching expenses, and a breakdown list grouped by the requested field

## Project Structure

```
expense-tracker-mcp/
├── main.py                 # Entry point for the MCP server
├── src/
│   └── expense_tracker_mcp/
│       ├── __init__.py
│       ├── server.py       # MCP server implementation with expense tools
│       └── db.py           # SQLite database persistence layer
├── pyproject.toml          # Project configuration
├── expenses.db             # SQLite database (auto-created, gitignored)
└── README.md               # This file
```

## Features

- Full expense tracking via MCP protocol
- SQLite database for persistent storage
- Add, list, edit, and delete expenses
- Filter expenses by date, category, and sub-category
- Summarize expenses with customizable groupings
- Predefined expense categories and sub-categories
- FastMCP integration for easy server setup
- Compatible with MCP Inspector for testing

## Data Storage

Expenses are stored in a SQLite database (`expenses.db`) with the following schema:

- `id`: Primary key (auto-increment)
- `date`: Expense date (YYYY-MM-DD format)
- `amount`: Amount spent
- `category`: Expense category
- `sub_category`: Optional sub-category
- `note`: Optional free-text note

The database is automatically created on first run and is excluded from version control via `.gitignore`.

## License

MIT