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

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

---

2. Create Virtual Environment

Linux / macOS

python -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate

---

3. Install Dependencies

Using uv (Recommended)

pip install uv
uv pip install -e .

Using pip

pip install -e .

---

4. Configure Environment Variables

Create a .env file in the project root.

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

Replace the connection string with your MongoDB URI.

Example:

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

---

🗄️ Database Setup

Create a users collection.

Each authenticated user should have a document similar to:

{
  "_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:

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:

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

---

list_expenses

Lists expenses between two dates.

Required:

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

---

summarize_expense

Returns grouped expense totals.

Required:

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

Optional:

{
  "category": "Food"
}

---

edit_expense

Update any expense field.

Example:

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

---

delete_expense

Delete an expense permanently.

{
  "expense_id": "687ec8769ef34217"
}

---

📁 Project Structure

.
├── 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! 🚀