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")

Related MCP server: expense-tracker-mcp-server

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().