# Finance Tracking MCP

A small [MCP](https://modelcontextprotocol.io) server for tracking personal expenses, built with [FastMCP](https://github.com/jlowin/fastmcp) and SQLAlchemy on top of SQLite.

## Tools

| Tool | Description |
| --- | --- |
| `add_expense` | Add a new expense (title, amount, category, optional date and note). Defaults to today's date. |
| `edit_expense` | Update an existing expense by ID — only the fields you pass are changed. |
| `expense_summary` | Totals and a per-category breakdown, optionally filtered by category and/or month (`YYYY-MM`). |

## Resources

| URI | Description |
| --- | --- |
| `expense://categories` | The category list from `categories.json`, served as JSON. |

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)

## Running

```bash
uv run main.py
```

The server creates `expenses.db` next to `main.py` on first run. That file is gitignored, so your data stays local.

## Using it with Claude

Add the server to your MCP client config, for example:

```json
{
  "mcpServers": {
    "finance-tracking": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/finance-tracking-mcp", "main.py"]
    }
  }
}
```

## Project layout

```
main.py           # MCP server: tools, resource, and SQLAlchemy models
categories.json   # Category list exposed via the expense://categories resource
pyproject.toml    # Project metadata and dependencies
```