# 📘 Expense Tracker MCP Server

AI-powered budgeting, smart expense tracking, and affordability insights using the Model Context Protocol (MCP).

The Expense Tracker MCP Server provides a complete financial tracking engine that integrates budgeting, expense ingestion, smart category detection, and affordability analytics—all via the Model Context Protocol so AI assistants can interact with your financial data safely and intelligently.

---

## 🚀 Features

### ✅ Budget Management
- Create total-only or category-based monthly budgets
- Validate category allocations and auto-suggest corrections
- Convert budgets from total-only → category-mode
- Graceful error handling and flexible month parsing

### ✅ Expense Management
- **Add expenses** with smart category & subcategory detection
- Auto date parsing ("yesterday", "next Monday", "Jan 5")
- Duplicate detection and budget impact analysis
- **Bulk add expenses** (NLP friendly, validated, error-tolerant)
- Update & delete expenses with validation & safety prompts

### ✅ Affordability Engine
- Predict affordability before adding expenses
- Total-budget and category-budget aware
- Impact percentage + status levels
- Consistent logic across all modules

### ✅ Insights & Analytics
- Summaries by month, category, or date ranges
- Remaining budget calculations and trend extraction
- Days remaining in month tracking
- Human-readable status indicators

### ✅ Smart Category Detection
- AI-powered heuristics for auto-category assignment
- Keyword extraction and confidence-based assignment
- Fallback suggestions when uncertain
- Works for both bulk and single expenses

### ✅ Human-Friendly Design
- Suggestions instead of hard errors
- Clarification prompts and auto-fixes for common mistakes
- Safe delete operations with confirmation
- Full MCP-compatible error handling

---

## 🏗️ Project Structure

```
expense-tracker-mcp/
│
├── server.py                  # MCP server entrypoint
├── config.py                  # Category config & paths
│
├── modules/                   # MCP tool implementations
│   ├── budget.py              # Budget tools (set, list, remaining)
│   ├── expenses.py            # Add, update, delete, bulk-add
│   ├── affordability.py       # Affordability analysis
│   ├── search.py              # Query expenses/budgets
│   └── insights.py            # Higher-level analytics
│
├── utils/                     # Core business logic
│   ├── database.py            # SQLite connection + init
│   ├── budget_core.py         # Core budget logic
│   ├── expenses_core.py       # Core DB I/O for expenses
│   ├── affordability_core.py  # Core affordability logic
│   ├── category_detection.py # Keyword & heuristic-based detection
│   ├── date_utils.py          # Flexible date parsing
│   ├── status.py              # Budget status levels
│   └── __init__.py            # Aggregated exports
│
├── data/
│   ├── budgets.json           # Stored budget data
│   └── expenses.db            # SQLite expense database
│
└── resources/
    └── categories.json        # Category → subcategories mapping
```

---

## ⚙️ Installation & Setup

### 1. Clone the Repository
```bash
git clone https://github.com/Khushi-c-sharma/expense-tracker-mcp-server-improvised.git
cd expense-tracker-mcp
```

### 2. Create and Activate a Virtual Environment
```bash
# Create virtual environment
python -m venv .venv

# Activate (Windows)
.\.venv\Scripts\activate

# Activate (macOS/Linux)
source .venv/bin/activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Initialize the Database
The server automatically initializes the SQLite database on startup—no manual setup required.

### 5. Run the Server

**For Claude Desktop integration:**
```bash
fastmcp dev server.py
```

**For testing/development:**
```bash
fastmcp run server.py
```

---

## 🔌 Claude Desktop Integration

To use this server with Claude Desktop, add the following to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "dev",
        "/absolute/path/to/expense-tracker-mcp/server.py"
      ]
    }
  }
}
```

Replace `/absolute/path/to/` with your actual path, then restart Claude Desktop.

---

## 🧰 Available Tools

### 🔹 Budget Tools
| Tool | Description |
|------|-------------|
| `set_monthly_budget` | Set total or category-based budgets |
| `get_remaining_budget` | Check remaining money by month/category |
| `list_budgets` | View all budget configurations |
| `convert_to_category_budget` | Transform simple budgets into category budgets |

### 🔹 Expense Tools
| Tool | Description |
|------|-------------|
| `add_expense` | Add expenses with smart category detection |
| `bulk_add_expenses` | Add multiple expenses at once (validated & robust) |
| `update_expense` | Safely update amount/category/date/description |
| `delete_expense` | Safe delete with confirmation |
| `get_category_info` | Get rules for categories/subcategories |

### 🔹 Affordability Tools
| Tool | Description |
|------|-------------|
| `check_affordability` | Predict impact before adding an expense |

### 🔹 Insights Tools
| Tool | Description |
|------|-------------|
| `monthly_summary` | Summaries of spending by month |
| `category_breakdown` | Category-level insights |
| `remaining_days_info` | Insights with days remaining |

### 🔹 Search Tools
| Tool | Description |
|------|-------------|
| `search_expenses` | Query expenses by text/category/date |
| `search_budget` | Find budgets easily |
| `smart_lookup` | Intelligent search ("What did I spend on food last week?") |

---

## 🧪 Testing

To ensure module compatibility and catch issues early:

```bash
pip install pytest
python -m pytest -q
```

Our tests verify that all modules load without import errors, validate API shapes, and catch schema issues before deployment.

---

## 🎯 Design Philosophy

### ✔ Human-First UX
Errors guide users with suggestions rather than blocking them completely.

### ✔ Strict Tool API Discipline
MCP-safe signatures (no `**kwargs`), predictable schemas, and consistent behavior.

### ✔ Separation of Concerns
- **`modules/`** → Conversational logic and MCP tool implementations
- **`utils/`** → Pure core business logic
- **`server.py`** → MCP integration layer

### ✔ Extensible Architecture
Adding new tools or insights is straightforward thanks to the modular design.

---

## 📈 Future Enhancements

- [ ] Machine learning–based category predictions
- [ ] OCR receipt scanning → auto expense import
- [ ] Real-time spending limit notifications
- [ ] Expense tagging system
- [ ] Multi-user support
- [ ] CSV/Excel bulk import tools
- [ ] Auto-recurring expenses (rent, subscriptions)
- [ ] Budget forecasting and projections
- [ ] Integration with banking APIs
- [ ] Mobile app companion

---

## 💬 Contributing

We welcome contributions! Feel free to open issues or pull requests to:

- Add new features
- Improve category detection heuristics
- Suggest new insights and analytics
- Expand test coverage
- Improve documentation

---

## 📝 License

[Add your license here - MIT, Apache 2.0, etc.]

---

## 🧠 About

This project was built to serve as the backend brain for AI budgeting assistants using the Model Context Protocol. It emphasizes:

- **Reliability** → Robust error handling and validation
- **Explainability** → Clear feedback and suggestions
- **Graceful Handling** → User-friendly error messages
- **Human-Friendly Responses** → Natural language interactions

Your server is now one of the most feature-rich MCP financial engines available, ready to power intelligent personal finance assistants.

---

## 🙏 Acknowledgments

Built with [FastMCP](https://github.com/jlowin/fastmcp) and powered by the [Model Context Protocol](https://modelcontextprotocol.io/).