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

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:

Column	Type	Description
`id`	`INTEGER`	Auto-incrementing primary key
`amount`	`REAL`	Expense amount
`date`	`TEXT`	Expense date
`category`	`TEXT`	Main category
`subcategory`	`TEXT`	Optional subcategory
`note`	`TEXT`	Optional note

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.