# Expense Tracker MCP Server

An asynchronous Model Context Protocol (MCP) server built with Python and [FastMCP](https://github.com/jcarter3/fastmcp) to log and track personal expenses inside a local SQLite database with strict category/subcategory checks.

## Features

- **SQLite Database Backend**: Logs expenses locally in `expenses.db` using `aiosqlite`.
- **Asynchronous Execution**: Fully utilizes `asyncio` and async database connections.
- **Categorization**: Validates categories and subcategories against a custom JSON hierarchy (`categories.json`).
- **Exposed Tools**:
  - `add_expense`: Add a new transaction (validates amount, category, and dates).
  - `get_expenses`: View matching logs with optional category, subcategory, start date, and end date filters.
  - `get_expense_summary`: View spent totals, item count, and percentages grouped by category.
  - `delete_expense`: Remove transaction logs by database ID.
- **Exposed Resources**:
  - `expense://categories`: Returns the JSON representation of categories and their subcategories.
  - `expense://categories/{category}/subcategories`: Returns subcategories for a given category in JSON format.

## Files Structure

- [main.py](file:///d:/coding/expense-tracker-mcp-server/main.py): Server entrypoint containing initialization, SQLite queries, MCP tools, and MCP resource declarations.
- [categories.json](file:///d:/coding/expense-tracker-mcp-server/categories.json): Configuration file specifying categories and subcategories.
- [pyproject.toml](file:///d:/coding/expense-tracker-mcp-server/pyproject.toml): Package configuration with metadata and dependency requirements (`fastmcp` and `aiosqlite`).
- [.gitignore](file:///d:/coding/expense-tracker-mcp-server/.gitignore): Configured to ignore virtual environments, cache directories, and local database files.

## Installation

Ensure you have [uv](https://github.com/astral-sh/uv) installed.

To sync dependencies:
```bash
uv sync
```

## Running the Server

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

## Development and Testing

A test suite is available under the artifacts directory. To run the async test suite:
```bash
uv run python C:\Users\User\.gemini\antigravity-ide\brain\7f833c64-f9e4-404b-a691-0d0df923616c\scratch\test_server.py
```