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

📋 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

add_expense

Creates a new expense.

Required Parameters

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

🙏 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! 🚀