# Expense Tracker MCP Server

A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for recording, browsing, and summarizing expenses. It stores data locally in SQLite and exposes a curated category list as an MCP resource, so an MCP client can help keep spending records organized without relying on a hosted service.

## Features

- Add expenses with a date, amount, category, optional subcategory, and note
- List expenses within an inclusive date range
- Summarize spending by category, with an optional category filter
- Read the available categories and subcategories from `expense://categories`
- Persist everything locally in `expenses.db`

## Requirements

- Python 3.13 or newer
- [`uv`](https://docs.astral.sh/uv/) (recommended)

## Install

Clone the repository and install the project dependencies:

```bash
git clone https://github.com/ansh-rohilla/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server
uv sync
```

## Run the server

Start the server with:

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

The SQLite database is created automatically at `expenses.db` in the project root on first run.

## Configure an MCP client

Add the following server entry to your MCP client's configuration. Replace `/absolute/path/to` with the path where you cloned this repository.

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/expense-tracker-mcp-server",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}
```

For example, in Claude Desktop this entry belongs in `claude_desktop_config.json`. Restart the client after saving the configuration.

## Available tools

### `add_expense`

Adds an expense to the local database.

| Parameter | Required | Description |
| --- | --- | --- |
| `date` | Yes | Date of the expense, preferably `YYYY-MM-DD` |
| `amount` | Yes | Expense amount as a number |
| `category` | Yes | A top-level category such as `food` or `transport` |
| `subcategory` | No | A more specific category, such as `groceries` |
| `note` | No | Any useful context about the expense |

Example request:

```text
Add an expense of 450 on 2026-08-02 for groceries under food. Note: weekly vegetables.
```

### `list_expenses`

Returns expenses whose dates fall within the inclusive range.

| Parameter | Required | Description |
| --- | --- | --- |
| `start_date` | Yes | Beginning of the date range (`YYYY-MM-DD`) |
| `end_date` | Yes | End of the date range (`YYYY-MM-DD`) |

### `summarize`

Returns total spending grouped by category for an inclusive date range.

| Parameter | Required | Description |
| --- | --- | --- |
| `start_date` | Yes | Beginning of the date range (`YYYY-MM-DD`) |
| `end_date` | Yes | End of the date range (`YYYY-MM-DD`) |
| `category` | No | Limit the summary to one category |

## Categories resource

The server provides `expense://categories` as JSON. It reads from [`categories.json`](categories.json), which you can customize to match your own budgeting system. Common top-level categories include food, transport, housing, utilities, health, education, entertainment, shopping, travel, investments, and more.

## Data and privacy

Expenses remain on your machine in the local SQLite database. Back up `expenses.db` if you want to retain your records when moving or reinstalling the project. Because the database can contain personal financial information, avoid committing a populated copy to a public repository.

## Project layout

```text
.
├── main.py             # FastMCP server and expense tools
├── categories.json     # Available categories and subcategories
├── expenses.db         # Local SQLite database (created automatically)
├── pyproject.toml      # Project metadata and dependencies
└── uv.lock             # Locked dependency versions
```

## License

No license has been specified yet. Add a license file before distributing or reusing this project publicly.