# Expense Tracker MCP Server

A **Model Context Protocol (MCP)** server for managing personal expenses. This server exposes a set of MCP tools that allow AI agents to add, list, edit, summarize, and delete expenses. All data is stored in **MongoDB** and scoped to authenticated users.

---

## ✨ Features

- 🔐 **User Authentication**
  - Every request is authenticated using a **Bearer Token (API Key)**.
  - API keys are securely stored as **SHA-256 hashes**.

- 💰 **Expense Management**
  - Add new expenses
  - List expenses within a date range
  - Edit existing expenses
  - Delete expenses

- 📊 **Expense Summarization**
  - Aggregate expenses by category
  - Filter summaries by date range
  - Optional category filtering

- 🤖 **MCP Native**
  - Fully compatible with MCP-enabled AI agents.

- ⚡ **Asynchronous & Fast**
  - Built using **FastMCP** and **Motor** for high-performance asynchronous MongoDB operations.

---

# 🧰 Tech Stack

| Technology | Purpose |
|------------|---------|
| Python 3.11+ | Programming Language |
| FastMCP | MCP Server Framework |
| MongoDB | Database |
| Motor | Async MongoDB Driver |
| Uvicorn | ASGI Server |
| python-dotenv | Environment Variable Management |

---

# 📋 Prerequisites

Before running the project, ensure you have:

- Python 3.11+
- MongoDB (Local or MongoDB Atlas)
- Git
- *(Optional)* `uv` package manager

---

# 🚀 Installation

## 1. Clone the Repository

```bash
git clone https://github.com/Vikkaasshh/ExpenseTracker_MCP_Server.git
cd ExpenseTracker_MCP_Server
```

---

## 2. Create Virtual Environment

### Linux / macOS

```bash
python -m venv venv
source venv/bin/activate
```

### Windows

```powershell
python -m venv venv
venv\Scripts\activate
```

---

## 3. Install Dependencies

### Using uv (Recommended)

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

### Using pip

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

---

## 4. Configure Environment Variables

Create a `.env` file in the project root.

```env
MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/
```

Replace the connection string with your MongoDB URI.

Example:

```env
MONGODB_URI=mongodb+srv://admin:password123@cluster0.mongodb.net/
```

---

# 🗄️ Database Setup

Create a **users** collection.

Each authenticated user should have a document similar to:

```json
{
  "_id": ObjectId("64b5fdf82bc9d0f4b0f92b72"),
  "api_key_hash": "f6c7cf74e35dca8d2b11f...",
  "is_active": true
}
```

The `api_key_hash` must contain the SHA-256 hash of the user's API key.

---

# ▶️ Running the Server

Run locally:

```bash
python main.py
```

The server starts at:

```
http://0.0.0.0:8000
```

MCP endpoint:

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

---

# 🤖 Connecting an MCP Client

Any MCP-compatible client can connect to the server.

Examples:

- Claude Desktop
- MCP Inspector
- Custom MCP Clients

### Endpoint

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

### Authentication Header

```
Authorization: Bearer <your_api_key>
```

---

# 🛠️ Available MCP Tools

| Tool | Description | Required Parameters |
|------|-------------|--------------------|
| **add_expense** | Add a new expense | `date`, `amount`, `category` |
| **list_expenses** | List expenses | `start_date`, `end_date` |
| **summarize_expense** | Summarize expenses by category | `start_date`, `end_date` |
| **edit_expense** | Update an expense | `expense_id` + fields |
| **delete_expense** | Delete an expense | `expense_id` |

---

## add_expense

Creates a new expense.

### Required Parameters

| Parameter | Type |
|------------|------|
| date | YYYY-MM-DD |
| amount | float |
| category | string |

### Optional Parameters

- subcategory
- note

Example:

```json
{
  "date": "2026-01-10",
  "amount": 199.99,
  "category": "Food",
  "subcategory": "Restaurant",
  "note": "Dinner"
}
```

---

## list_expenses

Lists expenses between two dates.

Required:

```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}
```

---

## summarize_expense

Returns grouped expense totals.

Required:

```json
{
  "start_date": "2026-01-01",
  "end_date": "2026-01-31"
}
```

Optional:

```json
{
  "category": "Food"
}
```

---

## edit_expense

Update any expense field.

Example:

```json
{
  "expense_id": "687ec8769ef34217",
  "amount": 350,
  "note": "Updated amount"
}
```

---

## delete_expense

Delete an expense permanently.

```json
{
  "expense_id": "687ec8769ef34217"
}
```

---

# 📁 Project Structure

```text
.
├── main.py
├── auth.py
├── db.py
├── prompt.py
├── resources/
│   ├── categories.json
│   └── operation.json
├── pyproject.toml
├── uv.lock
└── README.md
```

### Description

| File | Purpose |
|------|---------|
| main.py | FastMCP application |
| auth.py | Authentication |
| db.py | MongoDB connection |
| prompt.py | AI system prompt |
| resources | Static resources |
| pyproject.toml | Project metadata |
| uv.lock | Dependency lock |
| README.md | Documentation |


# 🙏 Acknowledgments

Special thanks to:

- **FastMCP** for providing an excellent MCP framework.
- **MongoDB** for scalable document storage.
- **Motor** for asynchronous database operations.
- **Uvicorn** for high-performance ASGI serving.

---

# ⭐ Support

If you found this project useful:

- ⭐ Star the repository

---

## Happy Expense Tracking with AI! 🚀