# Expense Tracker MCP Server

A simple Expense Tracker MCP server built with FastMCP and SQLite.

## Features

* Add expenses
* List expenses by date range
* Summarize expenses by category
* Expose expense categories as an MCP resource
* Compatible with Claude Desktop and MCP Inspector

## Tech Stack

* Python 3.14+
* FastMCP 3.4.0
* SQLite

## Installation

Clone the repository and install dependencies:

```bash
uv sync
```

or

```bash
uv add fastmcp
```

## Project Structure

```text
.
├── main.py
├── expenses.db
├── categories.json
├── pyproject.toml
├── uv.lock
└── README.md
```

## Available Tools

### add_expense

Add a new expense record.

Parameters:

* date
* amount
* category
* subcategory (optional)
* note (optional)

Example:

```json
{
  "date": "2026-06-01",
  "amount": 600,
  "category": "transport",
  "subcategory": "cab_ride_hailing",
  "note": "Cab ride to Delhi"
}
```

### list_expenses

List expenses within a date range.

Parameters:

* start_date
* end_date

### summarize

Summarize expenses by category.

Parameters:

* start_date
* end_date
* category (optional)

## Available Resources

### expense://categories

Returns the contents of `categories.json`.

Example categories:

* food
* transport
* housing
* utilities
* health
* education
* entertainment
* shopping
* travel
* investments
* and more

## Running the MCP Server

Start the server:

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

## MCP Inspector

Launch the MCP Inspector for local testing:

```bash
uv run fastmcp dev inspector main.py
```

## Claude Desktop Integration

Install the server into Claude Desktop:

```bash
uv run fastmcp install claude-desktop main.py
```

Restart Claude Desktop after installation.

## Example Prompts

Add an expense:

```text
Add an expense of ₹600 for a cab ride to Delhi last Sunday.
```

List expenses:

```text
Show all expenses between 2026-06-01 and 2026-06-30.
```

Summarize expenses:

```text
Summarize my expenses for June 2026.
```