# Expense Tracker MCP Server

A lightweight local **MCP (Model Context Protocol)** server for tracking personal or small-team expenses. It lets you add expense entries, list transactions within a date range, and generate simple summaries by category — all backed by a local SQLite database.

This project is designed for simple, local-first expense management and easy integration with MCP-compatible clients. It also exposes a structured expense category resource so clients can present consistent category options without hardcoding them.

## Features

- **Add expenses** with a date, amount, category, optional subcategory, and note
- **List expenses** within an inclusive date range
- **Summarize spending** by category across a date range
- **Local SQLite storage** for fast, simple persistence
- **Category resource** served from `categories.json`
- **Easy customization** by editing the category file without restarting the server

## How it works

The server is built with **Python** and **FastMCP**.

When the app starts, it initializes a local SQLite database file called `expenses.db` and ensures the `expenses` table exists. The main entry point in `main.py` registers MCP tools for inserting expenses, fetching expense rows in a date range, and summarizing totals grouped by category. It also registers an MCP resource at `expense://categories`, which reads directly from `categories.json` each time it is requested.

Because the data is stored locally and the category resource is file-based, the project stays simple, portable, and easy to modify.

## Tech Stack

- **Language:** Python 3.11+
- **Runtime / Framework:** FastMCP
- **Database:** SQLite
- **Core library:** `fastmcp`

## Project Structure

```text
main.py          MCP server entry point and expense tools
categories.json  Category and subcategory taxonomy
expenses.db      Local SQLite database file
pyproject.toml   Project metadata and dependency definition
```

## Installation

Make sure you have **Python 3.11 or later** installed.

Clone the repository and install dependencies:

```bash
pip install fastmcp
```

If you are using a virtual environment, activate it first.

## Running the server

Start the MCP server with:

```bash
python main.py
```

This will launch the FastMCP server and initialize the local database if it does not already exist.

## Available MCP Tools

### `add_expense(date, amount, category, subcategory="", note="")`
Adds a new expense record to the database.

Example:

```json
{
  "date": "2026-07-14",
  "amount": 24.5,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch"
}
```

### `list_expenses(start_date, end_date)`
Returns all expense entries within the inclusive date range, ordered by record ID.

Example:

```json
{
  "start_date": "2026-07-01",
  "end_date": "2026-07-31"
}
```

### `summarize(start_date, end_date, category=None)`
Returns total spending grouped by category for the given date range. If `category` is provided, the summary is filtered to that category.

Example:

```json
{
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "category": "food"
}
```

## Available Resource

### `expense://categories`
Returns the category taxonomy defined in `categories.json` as JSON.

This file includes high-level categories such as:

- food
- transport
- housing
- utilities
- health
- education
- family_kids
- entertainment
- shopping
- subscriptions
- personal_care
- gifts_donations
- finance_fees
- business
- travel
- home
- pet
- taxes
- investments
- misc

Each category includes a set of subcategories for more specific expense classification.

## Category File

You can customize the available categories by editing `categories.json`.

Because the resource reads the file fresh every time it is accessed, you do not need to restart the server after changing categories.

## Example Usage

A typical flow looks like this:

1. Start the MCP server
2. Add expense entries with `add_expense`
3. Query records with `list_expenses`
4. Generate spending insights with `summarize`
5. Use `expense://categories` to drive category selection in a client

## Notes

- Expenses are stored in a local SQLite database file named `expenses.db`
- Dates are expected to be passed in a consistent text format, such as `YYYY-MM-DD`
- The project is intentionally minimal and may be extended with validation, editing, deletion, authentication, or richer reporting in the future

## Getting Started

If you are building an MCP-compatible expense assistant, this server is a compact starting point that you can run locally and extend as needed.