Expense Tracker MCP

A simple Model Context Protocol (MCP) server for tracking expenses in a local SQLite database. It exposes tools for adding, reading, updating, deleting, and summarizing expenses, plus a JSON resource containing supported categories and subcategories.

Features

• Add expenses with amount, date, category, subcategory, and note fields

• List all saved expenses

• Query expenses by start and end date

• Update existing expenses by ID

• Delete expenses by ID

• Summarize spending by category over a date range

• Read predefined expense categories from categories.json

• Store data locally in expenses.db

Related MCP server: Personal Finance Tracker

Requirements

• Python 3.13 or newer

• uv for dependency management, or another Python package manager

Installation

Clone the project and install dependencies:

uv sync

The main dependency is fastmcp, defined in pyproject.toml.

Running The Server

Start the MCP server:

uv run python main.py

By default, the server runs over HTTP on:

http://0.0.0.0:8000

The SQLite database is initialized automatically when the server starts. If expenses.db does not already contain the required table, it will be created.

MCP Tools

add_expense

Adds a new expense.

Parameters:

• amount (float): Expense amount

• date (str): Expense date, preferably in YYYY-MM-DD format

• category (str): Main expense category

• subcategory (str, optional): More specific category

• note (str, optional): Additional details

Example:

{
  "amount": 250.75,
  "date": "2026-07-08",
  "category": "food",
  "subcategory": "groceries",
  "note": "Weekly grocery run"
}

get_expenses

Returns all expenses stored in the database.

get_expense_by_start_end_date

Returns expenses between two dates.

Parameters:

• start_date (str): Start date

• end_date (str): End date

Example:

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

update_expense

Updates an existing expense by ID. Only fields provided in the request are updated.

Parameters:

• expense_id (int): Expense ID

• amount (float, optional): Updated amount

• date (str, optional): Updated date

• category (str, optional): Updated category

• subcategory (str, optional): Updated subcategory

• note (str, optional): Updated note

Example:

{
  "expense_id": 1,
  "amount": 300,
  "note": "Updated grocery total"
}

delete_expense

Deletes an expense by ID.

Parameters:

• expense_id (int): Expense ID to delete

summarize

Summarizes expenses by category for a date range.

Parameters:

• start_date (str): Start date

• end_date (str): End date

• category (str, optional): Filter summary to one category

Example:

{
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "category": "food"
}

MCP Resources

expenses://categories

Returns the contents of categories.json, which maps supported categories to their subcategories.

Example categories include:

• food

• transport

• housing

• utilities

• health

• education

• business

• travel

• investments

• misc

Data Model

Expenses are stored in the expenses SQLite table:

Project Structure

.
├── main.py           # FastMCP server and tool definitions
├── categories.json   # Category and subcategory definitions
├── expenses.db       # Local SQLite database
├── pyproject.toml    # Project metadata and dependencies
├── uv.lock           # Locked dependency versions
└── README.md

Notes

• Date values are stored as text. Use a consistent format such as YYYY-MM-DD so date-range queries work correctly.

• The database file is local to this project directory.

• The current implementation does not validate category names against categories.json; clients should use the categories resource to choose valid values.