# 💰 Expense Tracker MCP

## 🤖 AI-Powered Expense Management using Model Context Protocol

<p align="center"> </p> <p align="center"> <img src="https://img.shields.io/badge/Python-3.13-blue?style=for-the-badge&logo=python"/> <img src="https://img.shields.io/badge/FastMCP-3.4.4-purple?style=for-the-badge"/> <img src="https://img.shields.io/badge/MongoDB-Database-green?style=for-the-badge&logo=mongodb"/> <img src="https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi"/> </p>

---

# 📌 Overview

Expense Tracker MCP is an **AI-powered financial management system** built using**Model Context Protocol (MCP )**.

The system allows Large Language Models to interact with expense data throughMCP tools, enabling users to:

- Add expenses

- Search expenses

- Analyze spending patterns

- Generate financial insights

- Communicate with expense data using natural language

---

# 🧠 MCP Architecture

```mermaid
flowchart TB


USER["👤 User"]

CLIENT["🔌 MCP Client"]

SERVER["⚡ FastMCP Server"]

TOOLS["🛠 MCP Tools"]

FASTAPI["🚀 FastAPI Application"]

MONGO["🍃 MongoDB Database"]



USER --> CLIENT

CLIENT --> SERVER

SERVER --> TOOLS

TOOLS --> FASTAPI

FASTAPI --> MONGO
```

# 🚀 Key Features

💸 Expense Management✅ Create expenses✅ Update expenses✅ Delete expenses✅ Retrieve expense records✅ Store financial history

🔌 Model Context Protocol

This project implements MCP architecture:

User|MCP Client|FastMCP Server|Expense Tools|MongoDB

## 🛠️ Technology Stack

###🐍 Core Development

<p align="center"> <img src="https://skillicons.dev/icons?i=python"/> </p>
Python >= 3.13
Setuptools
Wheel

### ⚡ MCP Framework

<img src="https://img.shields.io/badge/FastMCP-3.4.4-purple?style=flat-square">
MCP Server implementation
Tool registration
LLM communication layer

### 🚀 Backend

<p align="center"> <img src="https://skillicons.dev/icons?i=fastapi"/> </p>
FastAPI
Uvicorn
REST APIs

### 🍃 Database

<p align="center"> <img src="https://skillicons.dev/icons?i=mongodb"/> </p>
MongoDB
PyMongo
Motor Async Driver

### 📦 Validation & Configuration

Pydantic v2Pydantic SettingsEnvironment Variablespython-dotenv

## 📂 Project Structure

```
Expense_Tracker/
│
├── app/
│   └── db/
│       ├── database.py       # MongoDB connection configurations & client initialization
│       └── application.py    # Core FastAPI application routing and logic
│
├── mcp/
│   ├── mcp_client.py         # MCP Client implementation for context bridging
│   └── mcp_server.py         # FastMCP Server registering the operational tools
│
├── .env                      # Local environment variable configuration
├── .gitignore                # Specified version control exclusions (e.g., venv, __pycache__ )
├── .python-version           # Explicit python version pinning
├── pyproject.toml            # Project metadata, dependencies, and editable tool configurations
└── README.md                 # System documentation## ⚙️ Installation
```

Clone repository:

```
git clone https://github.com/YOUR_USERNAME/Expense-Tracker-MCP.git

cd Expense-Tracker-MCP

Install dependencies:

pip install -e .
```

## 🔐 Environment Configuration

```

Create .env


MONGODB_URI=your_mongodb_connection_string

DATABASE_NAME=expense_tracker
```

▶️ Running Application

### Start MCP Server

-expense-server

or

```
python mcp_server.py
```

## 🌐 Remote MCP Server

This project also provides a remote MCP server that users can connect to:[https://expense-tracker-01.fastmcp.app/mcp](https://expense-tracker-01.fastmcp.app/mcp)

## API Documentation:

```
http://localhost:8000/docs
```

## 🔮 Future Improvements

-Expense prediction using ML-Budget recommendation engine-Voice-based expense entry-Multi-user authentication-React dashboard-Cloud deployment-Mobile application

## 👨‍💻 Developer

Sarim Abbas

AI Engineer | Backend Developer | Agentic AI Developer

<p align="center"> <img src="https://skillicons.dev/icons?i=python,fastapi,mongodb,docker,aws"/> </p>

⭐ Star this repository if you find it useful!