# Expense Tracker MCP

An [MCP](https://modelcontextprotocol.io/) server for recording and analyzing personal expenses. The server uses [FastMCP](https://gofastmcp.com/) and stores data locally in a SQLite database, so no external database service is required.

## Features

- Add an expense with a date, amount, category, subcategory, and note.
- List expenses for an inclusive date range.
- Summarize spending by category for an inclusive date range.
- Expose the category and subcategory list as the `expense://categories` MCP resource.
- Create the SQLite database automatically on first start.

 

## Installation

Clone or download the repository and open a terminal in the project directory:

```powershell
cd path\to\expenseTracker_mcp
```

Install the project and its dependencies with `uv`:

```powershell
uv sync
```

If `uv` is not installed, install it pip install uv

 
## Start the MCP server

Run the server over the default MCP stdio transport:

```powershell
uv run python -m expensetracker_mcp.main
```

Keep this process running while your MCP client connects to it. The first start creates `src/expensetracker_mcp/expenses.db` if it does not already exist.

### MCP client configuration

For an MCP client that supports a JSON server configuration, use the following entry and replace the path with the absolute path to this repository:

```json
{
	"mcpServers": {
		"expense-tracker": {
			"command": "uv",
			"args": [
				"--directory",
				"C:\\path\\to\\expenseTracker_mcp",
				"run",
				"python",
				"-m",
				"expensetracker_mcp.main"
			]
		}
	}
}
```

For a client that requires an absolute executable path, use the path to your `uv` installation instead of `uv`.

## Available MCP tools

### `add_expense`

Adds one expense entry.
 
### `list_expenses`

Lists all expenses between `start_date` and `end_date`, inclusive. Results are ordered by the database record ID.

### `summarize`

Totals expenses by category between `start_date` and `end_date`, inclusive. The optional `category` argument limits the result to one category.


## Categories resource

The `expense://categories` resource returns the contents of `src/expensetracker_mcp/categories.json` as JSON. It contains the supported top-level categories and their subcategories. The file is read each time the resource is requested, so category changes are available without restarting the server.