# Expense Tracker MCP

A local expense and income tracker backed by SQLite. The project provides a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for AI assistants (such as Claude Desktop, Cursor, and other MCP clients) and an optional FastAPI REST server for HTTP clients.

## Features

- **Expenses**: Add, list, edit, and delete expense records.
- **Income & Credits**: Store income/credit entries and calculate your current balance in real time.
- **Categorization**: Summarize spending grouped by category with optional date and category filters.
- **Category Catalog**: Load and query category/subcategory definitions from `categories.json`.
- **Local Storage**: All records are stored locally in SQLite (`expenses.db`), ensuring privacy.

## Technology Stack

- **Python**: 3.13 or newer
- **FastMCP**: High-performance MCP server implementation
- **SQLite**: Local relational storage
- **FastAPI & Uvicorn**: Optional REST API with OpenAPI documentation
- **uv**: Fast Python package and dependency manager

## Project Structure

```text
.
|-- expense_tracker.py       # Main FastMCP expense tracker server
|-- server.py                # Optional FastAPI REST API server
|-- categories.json          # Expense categories and subcategories catalog
|-- pyproject.toml           # Project metadata and dependencies (uv)
|-- uv.lock                  # Locked Python dependencies
|-- expenses.db              # Local runtime SQLite database (git-ignored)
`-- src/expense_tracker_mcp/ # Package entry point
    `-- __init__.py
```

## Setup

1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if not already installed.
2. Clone or navigate to this directory and sync dependencies:

```bash
# Sync core MCP dependencies
uv sync

# (Optional) Include FastAPI REST dependencies
uv sync --extra api
```

The database (`expenses.db`) and its tables are automatically created on first run:
- `expenses`: `id`, `date`, `amount`, `category`, `subcategory`, `note`
- `credit`: `id`, `date`, `amount`, `source`, `note`

---

## Running the MCP Server

Start the MCP server using either of the following commands:

```bash
uv run python expense_tracker.py
```

Or via the installed package command:

```bash
uv run expense-tracker-mcp
```

### Exposed MCP Tools

| Tool | Parameters | Description |
| --- | --- | --- |
| `add_expense` | `date`, `amount`, `category`, `subcategory`, `note` | Add an expense (date defaults to today). |
| `list_expenses` | `start_date`, `end_date`, `limit` | List expense records with optional date range and limit. |
| `summarize` | `start_date`, `end_date`, `category` | Group expenses by category and calculate totals. |
| `edit_expense` | `expense_id`, `date`, `amount`, `category`, `subcategory`, `note` | Update fields of an existing expense record. |
| `delete_expense` | `expense_id` | Delete an expense by ID. |
| `add_credit` | `date`, `amount`, `source`, `note` | Add an income or credit record. |
| `list_credits` | `limit` | List recent credit entries. |
| `get_balance` | *(none)* | Return total credits, total expenses, and current balance. |

### Exposed MCP Resources

| Resource URI | MIME Type | Description |
| --- | --- | --- |
| `expense://categories` | `application/json` | Provides the category catalog from `categories.json`. |

---

## Configuring with MCP Clients (e.g. Claude Desktop)

To connect this server to **Claude Desktop**, add the configuration below to your `claude_desktop_config.json`:

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\Dell\\OneDrive\\Desktop\\Expense_tracker_mcp",
        "python",
        "expense_tracker.py"
      ]
    }
  }
}
```

*(Replace the path with the absolute path to your project directory).*

---

## Running the REST API

`server.py` provides equivalent HTTP endpoints and interactive OpenAPI documentation.

Start the API:

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

- API Base URL: `http://localhost:8000`
- Interactive Swagger UI: `http://localhost:8000/docs`

### Main REST Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| `POST` | `/expenses` | Add a new expense |
| `GET` | `/expenses` | List expenses (supports `start_date`, `end_date`, `limit`) |
| `PATCH` | `/expenses/{expense_id}` | Update an existing expense |
| `DELETE` | `/expenses/{expense_id}` | Delete an expense |
| `GET` | `/expenses/summary` | Get expense summary by category |
| `POST` | `/credits` | Add a credit / income entry |
| `GET` | `/credits` | List credit entries |
| `GET` | `/balance` | Get current balance |
| `GET` | `/categories` | Retrieve categories catalog |

### Example Request

```bash
curl -X POST http://localhost:8000/expenses \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.50,
    "category": "food",
    "subcategory": "dining_out",
    "note": "Lunch"
  }'
```

---

## Data and Privacy

All financial records are stored locally in `expenses.db` within the project root. This file is excluded by `.gitignore` to prevent sensitive financial data from being committed to version control.