# 💰 Expense Tracker MCP Server

A powerful, AI-ready expense tracking system built with **FastMCP** (Model Context Protocol) that integrates seamlessly with Claude AI and other LLM applications.

**🎯 Status:** Production-Ready | **📊 Database:** SQLite | **🚀 Framework:** FastMCP 3.4.2

---

## ✨ Features

### 🎯 **Core Expense Management**
- ✅ **Add Expenses** - Track daily spending with category, subcategory, and notes
- ✅ **List Expenses** - Query expenses by date range
- ✅ **Summarize** - Category-wise expense breakdown with totals

### 💰 **Budget Management**
- ✅ **Set Budget** - Define monthly budgets per category
- ✅ **Check Budget Status** - Real-time budget vs actual spending with 🔴🟡🟢 status indicators
- ✅ **Budget Alerts** - Automatic warnings at 80% budget usage

### 📊 **Analytics & Insights**
- ✅ **Spending Trends** - Weekly trend analysis (last 30 days)
- ✅ **Advanced Analytics** - Highest/lowest expenses, median, averages per category
- ✅ **Smart Insights** - AI-generated spending patterns and recommendations
- ✅ **Monthly Reports** - Comprehensive month-end summaries

### 🔄 **Recurring Expenses**
- ✅ **Add Recurring Expenses** - Subscriptions, rent, bills (daily/weekly/monthly/yearly)
- ✅ **List Recurring** - View all active subscriptions with estimated monthly cost

### 🎯 **Savings Goals**
- ✅ **Create Savings Goals** - Vacation, emergency fund, new gadgets, etc.
- ✅ **Track Progress** - Update and monitor goal achievements
- ✅ **View All Goals** - Dashboard with progress percentages and deadlines

### 🔮 **Forecasting**
- ✅ **Expense Forecast** - Predict next month expenses (70% historical + 30% recurring)
- ✅ **Spending Prediction** - AI-powered forecasting based on patterns

---

## 🛠️ Installation

### **Prerequisites**
- Python 3.8+
- pip or uv (recommended)

### **Step 1: Clone Repository**
```bash
git clone https://github.com/mhd-faraz/Expense-Tracker-MCP.git
cd Expense-Tracker-MCP
```

### **Step 2: Create Virtual Environment**
```bash
# Using uv (faster)
uv venv
source .venv/bin/activate

# Or using Python venv
python3 -m venv .venv
source .venv/bin/activate
```

### **Step 3: Install Dependencies**
```bash
uv add fastmcp aiosqlite
```

### **Step 4: Run Server**
```bash
python3 main.py
```

**Expected Output:**
```
✅ Database initialized with all tables - write access confirmed
INFO: Uvicorn running on http://0.0.0.0:8321/mcp (Press CTRL+C to quit)
```

---

## 📖 Usage

### **Option 1: MCP Inspector (Testing)**

1. Open browser: `http://localhost:8321/mcp/inspector`
2. Select tool from dropdown
3. Fill parameters
4. Click "Run Tool"

**Example:**
```json
{
  "date": "2026-06-19",
  "amount": 450,
  "category": "Food & Dining",
  "subcategory": "Restaurant",
  "note": "Lunch with team"
}
```

### **Option 2: Claude Desktop (Production)**

1. Connect to this MCP server in Claude Desktop
2. Use natural language:

```
"Add an expense of ₹3000 for groceries today"
"Show my spending trends for the last 30 days"
"What's my budget status for this month?"
"Create a savings goal of ₹50000 for vacation by December"
"Forecast my next month expenses"
```

Claude will automatically call the appropriate tools and update your database!

### **Option 3: Python Script**

```python
import aiosqlite
import asyncio

async def add_expense():
    async with aiosqlite.connect("/tmp/expenses.db") as db:
        await db.execute(
            "INSERT INTO expenses(date, amount, category, note) VALUES (?,?,?,?)",
            ("2026-06-19", 450, "Food & Dining", "Lunch")
        )
        await db.commit()

asyncio.run(add_expense())
```

---

## 🗄️ Database Schema

### **expenses**
```sql
CREATE TABLE expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

### **budgets**
```sql
CREATE TABLE budgets(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT NOT NULL,
    amount REAL NOT NULL,
    month TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(category, month)
)
```

### **recurring_expenses**
```sql
CREATE TABLE recurring_expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    frequency TEXT NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

### **savings_goals**
```sql
CREATE TABLE savings_goals(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    goal_name TEXT NOT NULL,
    target_amount REAL NOT NULL,
    current_amount REAL DEFAULT 0,
    deadline TEXT NOT NULL,
    category TEXT DEFAULT 'Savings',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
```

**Database Location:** `/tmp/expenses.db` (macOS/Linux)

---

## 🔧 Available Tools (13 Total)

| # | Tool | Purpose | Parameters |
|---|------|---------|------------|
| 1 | `add_expense()` | Add new expense | date, amount, category, subcategory, note |
| 2 | `list_expenses()` | Query expenses | start_date, end_date |
| 3 | `summarize()` | Category summary | start_date, end_date, category |
| 4 | `set_budget()` | Set monthly budget | category, amount, month |
| 5 | `check_budget_status()` | Budget tracking | month |
| 6 | `add_recurring_expense()` | Add subscription | name, amount, category, frequency, start_date |
| 7 | `list_recurring_expenses()` | View subscriptions | (no params) |
| 8 | `create_savings_goal()` | New savings target | goal_name, target_amount, deadline, category |
| 9 | `update_savings_goal_progress()` | Track progress | goal_id, amount_saved |
| 10 | `get_savings_goals()` | View all goals | (no params) |
| 11 | `get_spending_trends()` | Weekly trends | days |
| 12 | `get_expense_analytics()` | Detailed stats | start_date, end_date |
| 13 | `forecast_expenses()` | Next month prediction | months_ahead |
| 14 | `get_smart_insights()` | AI recommendations | (no params) |
| 15 | `generate_monthly_report()` | Monthly summary | month |

---

## 📊 Example Outputs

### **Budget Status:**
```
Category          Budget    Spent     Remaining  Usage%   Status
Food & Dining     ₹5000     ₹2300     ₹2700      46.0%    🟢 OK
Transportation    ₹3000     ₹1200     ₹1800      40.0%    🟢 OK
Bills & Utilities ₹4000     ₹2500     ₹1500      62.5%    🟢 OK
```

### **Smart Insights:**
```
🎯 TOP SPENDING
   Food & Dining is your biggest expense (₹2300) - 35.2% of budget

📊 FREQUENCY
   Transportation has most transactions (4 times). Small amounts add up!

📈 DAILY PACE
   You're spending ₹473 per day on average

💡 OPTIMIZATION
   You have 3 categories eating >20% of budget. Consider consolidating!
```

### **Forecast:**
```
Category          Predicted    vs Last Month
Bills & Utilities ₹6429.70     ↑ +157.2%
Groceries         ₹2450.00     ↓ -30.0%
Food & Dining     ₹2060.00     ↓ -10.4%
```

---

## 🚀 Connect to Claude Desktop

### **Step 1: Get Server URL**
```
http://0.0.0.0:8321/mcp
```

### **Step 2: Add to Claude Settings**

In Claude Desktop, go to Settings → Connected Servers:
```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "python3",
      "args": ["/path/to/main.py"],
      "type": "stdio"
    }
  }
}
```

### **Step 3: Start Using!**

Now tell Claude:
```
"I spent ₹3000 on groceries today"
"Show my monthly budget status"
"Create a savings goal for my vacation"
"What are my spending trends?"
```

---

## 📁 Project Structure

```
Expense-Tracker-MCP/
├── main.py                      # Main MCP server (13 tools)
├── test_expense_tracker.py      # Complete test suite
├── categories.json              # Category definitions
├── .gitignore                   # Git ignore rules
├── README.md                    # This file
└── .venv/                       # Virtual environment
```

---

## 🧪 Testing

Run the complete test suite:

```bash
python3 test_expense_tracker.py
```

**Output includes:**
- ✅ 10 sample expenses
- ✅ 5 budget configurations
- ✅ 5 recurring expenses
- ✅ 4 savings goals
- ✅ All 15 tools tested
- ✅ Formatted analytics and reports

---

## 🔐 Security & Best Practices

- ✅ Database uses WAL mode for concurrent access
- ✅ Async/await for non-blocking operations
- ✅ Input validation on all parameters
- ✅ Proper error handling with meaningful messages
- ✅ Database transactions for data integrity

---

## 📈 Tech Stack

- **Framework:** FastMCP 3.4.2
- **Database:** SQLite 3
- **Async Runtime:** asyncio + aiosqlite
- **Server:** Uvicorn
- **Language:** Python 3.12+

---

## 🎯 Use Cases

1. **Personal Finance Tracking** - Daily expense logging
2. **Budget Planning** - Monthly budget management
3. **Goal Tracking** - Savings and financial targets
4. **Spending Analysis** - Trend analysis and forecasting
5. **AI Integration** - Natural language expense tracking via Claude

---

## 📝 Categories Supported

```
Food & Dining      Bills & Utilities    Healthcare
Transportation     Entertainment        Travel
Shopping           Education            Business
Subscriptions      Groceries           Personal Care
Other
```

---

## 🤝 Contributing

This is a portfolio project. Feel free to fork and extend!

**Ideas for enhancement:**
- Export to CSV/PDF
- Multi-user support
- Cloud sync
- Mobile app integration
- Advanced ML predictions

---

## 📄 License

MIT License - Feel free to use and modify!

---

## 👨‍💻 Author

**Faraz** - CS Engineering Graduate (2025)  
Portfolio: [faraz-portfolio-ivvo-xi.vercel.app](https://faraz-portfolio-ivvo-xi.vercel.app)  
GitHub: [@mhd-faraz](https://github.com/mhd-faraz)

---

## 🙋 FAQ

**Q: Database file empty?**  
A: Database files are binary. Use `list_expenses()` tool to verify data exists.

**Q: Can I use this without Claude Desktop?**  
A: Yes! Use MCP Inspector or call tools directly via Python.

**Q: How do I reset all data?**  
A: Delete `/tmp/expenses.db` and restart server.

**Q: Can I host this online?**  
A: Yes! Deploy to MCPCloud, Vercel, or Railway.

---

## 🚀 Next Steps

1. ✅ Clone this repo
2. ✅ Run `python3 main.py`
3. ✅ Open `http://localhost:8321/mcp/inspector`
4. ✅ Test a tool
5. ✅ Connect to Claude Desktop
6. ✅ Start tracking expenses with AI!

---

**Happy Expense Tracking! 💰✨**