# Monthly Expense MCP Server

A local MCP (Model Context Protocol) server that tracks your monthly expenses.
Data is stored in `expenses.json` right next to `server.py` — no external
database needed.

## Tools it exposes

- **add_expense** — add an expense (date, category, amount, description)
- **list_expenses** — list expenses, optionally filtered by month/category
- **delete_expense** — remove an expense by id
- **monthly_summary** — total + per-category breakdown for a month, plus
  budget status if you've set one
- **set_budget** — set/update a budget for a given month
- **list_categories** — see all categories you've used

## Setup with uv

1. **Install uv** if you don't already have it:
  https://docs.astral.sh/uv/getting-started/installation/

2. **Create the environment and install FastMCP.** Open a terminal/PowerShell
  in this folder and run:

   ```
  uv sync
   ```

3. **Run the server** (it waits for MCP messages on stdin, which is normal):

   ```
  uv run python server.py
   ```

   Press Ctrl+C to stop it.

The server is implemented in `server.py` with FastMCP. `uv sync` creates the
local `.venv`, installs the locked dependencies, and generates `uv.lock`.

## Connect it to Claude Desktop

Open your Claude Desktop config file:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add (or merge into) the `mcpServers` section:

```json
{
  "mcpServers": {
    "monthly-expense": {
      "command": "C:\\Users\\reenu\\Desktop\\monthly-expense-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\reenu\\Desktop\\monthly-expense-mcp\\server.py"
      ]
    }
  }
}
```

Save the file and fully restart Claude Desktop. You should then see the
expense tools available (look for the 🔨 tools icon in a new chat).

## Example usage once connected

- "Add an expense: $45.20 for groceries on 2026-08-15"
- "Show me all my expenses for August 2026"
- "Set my August budget to $2000"
- "Give me my August spending summary"
- "Delete expense #3"

## Notes

- All data lives in `expenses.json` in this folder — back it up if you care
  about the history. Delete that file to start fresh.
- This server only runs locally; it doesn't send your data anywhere.