# 💰 ExpenseTracker MCP Server

A lightweight and scalable **Expense Tracking MCP Server** built using FastMCP and SQLite. This server allows you to add, list, and summarize expenses efficiently, making it ideal for personal finance management or integration with MCP-compatible clients like Claude Desktop.

---

## 🚀 Features

* ✅ Add expenses with category and notes
* 📊 List expenses within a date range
* 📈 Summarize expenses by category
* 📂 Default categories support (with fallback)
* ⚡ Async database operations using `aiosqlite`
* ☁️ Cloud-ready (FastMCP deployment compatible)

---

## 🛠️ Tech Stack

* **Python**
* **FastMCP**
* **SQLite (aiosqlite for async support)**

---

## 📁 Project Structure

```
.
├── main.py              # Main MCP server file
├── requirements.txt    # Dependencies
├── categories.json     # (Optional) Custom categories
└── README.md
```

---

## ⚙️ Setup & Installation

### 1. Clone the repository

```bash
git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name
```

### 2. Create virtual environment

```bash
python -m venv venv
venv\Scripts\activate   # Windows
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

---

## ▶️ Running the Server

```bash
python main.py
```

Server will start at:

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

---

## 🌐 MCP Endpoint

Once deployed on FastMCP, your endpoint will look like:

```
https://your-app-name.fastmcp.app/mcp
```

⚠️ Note: Authentication is required to access this endpoint.

---

## 📌 Available Tools

### ➤ Add Expense

Adds a new expense entry.

**Parameters:**

* `date` (YYYY-MM-DD)
* `amount` (float)
* `category` (string)
* `subcategory` (optional)
* `note` (optional)

---

### ➤ List Expenses

Fetch expenses within a date range.

**Parameters:**

* `start_date`
* `end_date`

---

### ➤ Summarize Expenses

Get category-wise expense summary.

**Parameters:**

* `start_date`
* `end_date`
* `category` (optional)

---

## 📂 Categories Resource

Endpoint:

```
expense:///categories
```

* Loads from `categories.json` if available
* Falls back to default categories if file is missing

---

## 🧠 How It Works

* Uses a temporary directory for database storage
* Initializes database on startup
* Uses async operations for better performance
* Safe fallback mechanisms for missing files

---

## ⚠️ Common Issues & Fixes

### ❌ Pre-flight check failed

* Ensure your file name is `main.py`
* Make sure `mcp = FastMCP(...)` is correct
* Check logs for missing dependencies

### ❌ Module not found

* Add missing packages to `requirements.txt`

Example:

```
fastmcp
aiosqlite
```

---

## 💡 Future Improvements

* User authentication system
* Dashboard UI
* Monthly budget tracking
* Data export (CSV/Excel)

---

## 👨‍💻 Author

Built with ❤️ for learning and real-world MCP integration.

---

## ⭐ Support

If you like this project:

* Star ⭐ the repo
* Share with others
* Contribute improvements

---