# Expense Tracker MCP Server

This project is a Model Context Protocol (MCP) server for managing personal expenses. It exposes tools and a resource that can be used by MCP-compatible clients such as Claude Desktop or the FastMCP inspector.

## What it does

The server provides:

- `add_expense(date, amount, category, subcategory="", note="")` to store a new expense
- `list_expenses(start_date, end_date)` to retrieve expenses in a date range
- `summarize(start_date, end_date, category=None)` to group totals by category
- `expense://categories` as a JSON resource for category definitions

Expenses are stored in a local SQLite database created automatically when the server starts.

## Requirements

- Python 3.13 or newer
- [uv](https://docs.astral.sh/uv/) for dependency and script management

## Installation

From the project root:

```powershell
uv sync
```

This installs the project and its dependencies from the `pyproject.toml` file.

## Run locally with the MCP inspector

Start the server and inspect it in the FastMCP inspector:

```powershell
uv run fastmcp dev inspector src/expense_tracker_mcp_server/main.py
```

This opens the inspector UI and lets you test the tools and resources.

## Connect to Claude Desktop

To install the server into Claude Desktop, run:

```powershell
uv run fastmcp install claude-desktop src/expense_tracker_mcp_server/main.py
```

On Windows, Claude Desktop may store its config under a packaged-app path. If the default location is not detected, provide it explicitly:

```powershell
uv run fastmcp install claude-desktop --config-path "C:\Users\<your-user>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude" src/expense_tracker_mcp_server/main.py
```

Replace `<your-user>` with your Windows username.

## Project structure

```text
src/
  expense_tracker_mcp_server/
    __init__.py
    main.py
```

- `main.py` contains the MCP server implementation and tool definitions.
- `expenses.db` is created automatically at runtime in the package directory.
- `categories.json` is loaded as the `expense://categories` resource.

## Example usage

Once the server is running, you can call the tools with payloads such as:

```json
{
  "date": "2026-07-31",
  "amount": 42.5,
  "category": "Food",
  "subcategory": "Lunch",
  "note": "Team lunch"
}
```

## Notes

- The SQLite database is local to the project and will be created on first run.
- The categories resource is read from the JSON file each time it is requested, so edits are picked up without restarting the server.