ZeeshanML/expense-tracker-mcp-server

Expense Tracker MCP Server

A minimal Model Context Protocol (MCP) server for tracking personal expenses using SQLite, built with fastmcp.

Features

• Add expense: date, amount, category, optional subcategory and note
• List expenses: filter by inclusive date range
• Delete expense: remove by id
• Summarize: totals by category within a date range (optionally for a single category)
• Categories resource: expense://categories serves categories.json

Requirements

• Python: >= 3.13
• Optional: uv package manager (uv docs)

Quick start (uv)

# From the repo root
uv sync
uv run python main.py

Quick start (pip)

# From the repo root
python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install -U fastmcp
python main.py

Your MCP-compatible client can launch the server by executing python path/to/main.py (or uv run python main.py) via stdio.

Tools exposed

• add_expense(date, amount, category, subcategory="", note="") → { status, id }
• list_expenses(start_date, end_date) → array of expense objects
• delete_expense(id) → { status }
• summarize(start_date, end_date, category=None) → array of { category, total_amount }
• Resource: expense://categories → contents of categories.json

Dates are stored as text (ISO YYYY-MM-DD recommended). Amounts are REAL.

Data

• Database: expenses.db is created on first run with table expenses(id, date, amount, category, subcategory, note).
• Categories: Edit categories.json to customize categories/subcategories; the resource is read fresh on each request.

Notes

• This repo is intentionally simple to demonstrate an MCP server. Integrate it by configuring your MCP client to launch main.py.
• If you prefer a fresh database, delete expenses.db before starting the server.