Expense Tracker MCP Server

A Python-based FastMCP server for tracking personal expenses with MongoDB storage and a fixed category/subcategory model.

Project Overview

This repository implements an expense tracker as an MCP service using fastmcp. It stores expenses in a MongoDB collection and enforces a predefined set of categories and subcategories defined in categories.json.

The server exposes the following MCP tools:

• list_categories()
• add_expense(amount, category, subcategory, date=None, note=None)
• update_expense(expense_id, amount=None, category=None, subcategory=None, date=None, note=None)
• delete_expense(expense_id)
• list_expenses(start_date=None, end_date=None, category=None, limit=20)
• get_expense_summary(start_date=None, end_date=None, group_by="category")

Requirements

• Python 3.13 or newer
• MongoDB access via connection URI
• fastmcp
• python-dotenv
• pymongo

Setup

1. Create and activate a Python virtual environment.
2. Install dependencies:

pip install -r requirements.txt

3. Create a .env file at the project root with:

MONGODB_URI=<your-mongodb-uri>

4. Run the server:

python main.py

5. The server listens on port 8000 by default and can be overridden with the PORT environment variable.

Configuration

• main.py contains the MCP service configuration, database connection logic, and expense CRUD operations.
• categories.json defines the allowed categories and subcategories for every expense.
• render.yaml defines a Render deployment configuration that installs requirements and starts the service.

Expense Data Model

Each expense document includes:

• amount (float)
• category (string)
• subcategory (string)
• date (stored as a date object)
• note (optional string)
• created_at (UTC timestamp)

Expense IDs are stored as MongoDB _id values and returned as expense_id in serialized responses.

Usage Notes

• Use list_categories() before adding or updating an expense so you can choose valid category and subcategory values.
• Dates must be in YYYY-MM-DD format when provided.
• add_expense() requires a positive amount.
• update_expense() only changes the fields you provide.
• list_expenses() defaults to the most recent 20 expenses and supports filtering by date range and category.
• get_expense_summary() aggregates totals by category or by month.

Deployment on Render

The included render.yaml configures a Python web service:

• buildCommand: pip install -r requirements.txt
• startCommand: python main.py
• MONGODB_URI is expected from a Render-managed secret named mongodb_uri

Category Guidance

The app uses the category definitions from categories.json, so do not invent new categories or subcategories. If you need to verify valid values, call list_categories().