# Expense Tracker MCP

An AI-powered Expense Tracker built using **FastMCP** and **SQLite**. This project exposes expense management capabilities as MCP tools, allowing AI assistants such as Claude Desktop to interact with a persistent expense database through the Model Context Protocol (MCP).

---

## Features

- Add new expenses
- List expenses within a date range
- Update existing expenses
- Delete expenses
- Summarize expenses by category
- Expose expense categories as an MCP Resource
- Persistent local storage using SQLite

---

## Tech Stack

- Python 3.11+
- FastMCP
- SQLite
- JSON
- MCP (Model Context Protocol)

---

## Project Structure

```
Expense-Tracker-MCP/
│
├── main.py               # FastMCP server
├── database.py           # Database operations
├── categories.json       # Expense categories
├── expenses.db           # SQLite database (generated at runtime)
├── pyproject.toml
├── uv.lock
└── README.md
```

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `add_expense` | Add a new expense |
| `list_expenses` | Retrieve expenses between two dates |
| `update_expense` | Update an existing expense |
| `delete_expense` | Delete an expense by ID |
| `summarize_expenses` | Summarize expenses by category |

---

## MCP Resources

### `expense://categories`

Returns the list of supported expense categories and subcategories from `categories.json`.

---

## Installation

Clone the repository:

```bash
git clone https://github.com/navalmishra/Expense-Tracker-MCP.git
cd Expense-Tracker-MCP
```

Install dependencies:

```bash
uv sync
```

or

```bash
pip install -e .
```

---

## Running the Server

Start the FastMCP server:

```bash
python main.py
```

The server starts at:

```
http://localhost:8000/mcp
```

---

## Connecting with Claude Desktop

Add the server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "python",
      "args": [
        "/path/to/main.py"
      ]
    }
  }
}
```

Restart Claude Desktop, and the Expense Tracker tools will be available automatically.

---

## Example Workflow

Ask Claude:

> Add an expense of ₹500 for groceries today.

Claude calls:

```
add_expense(...)
```

Ask:

> Show my expenses for this month.

Claude calls:

```
list_expenses(...)
```

Ask:

> Summarize my food expenses.

Claude calls:

```
summarize_expenses(...)
```

---

## Database

The application uses SQLite for local persistence.

The database is created automatically on the first run if it does not already exist.

---

## Future Improvements

- Category validation using `categories.json`
- Pydantic models for input validation
- Monthly and yearly reports
- Expense analytics
- Budget tracking
- Cloud database support (PostgreSQL/Turso)
- Authentication
- Deployment on FastMCP Cloud

---

## Learning Objectives

This project demonstrates:

- Building custom MCP servers
- Creating MCP Tools and Resources
- Integrating SQLite with FastMCP
- Persistent AI applications
- Connecting custom MCP servers with Claude Desktop
- Deploying MCP servers to FastMCP Cloud

---

## License

This project is licensed under the MIT License.