Expense Tracker MCP Server

A lightweight local MCP (Model Context Protocol) server for tracking personal or small-team expenses. It lets you add expense entries, list transactions within a date range, and generate simple summaries by category — all backed by a local SQLite database.

This project is designed for simple, local-first expense management and easy integration with MCP-compatible clients. It also exposes a structured expense category resource so clients can present consistent category options without hardcoding them.

Features

• Add expenses with a date, amount, category, optional subcategory, and note
• List expenses within an inclusive date range
• Summarize spending by category across a date range
• Local SQLite storage for fast, simple persistence
• Category resource served from categories.json
• Easy customization by editing the category file without restarting the server

How it works

The server is built with Python and FastMCP.

When the app starts, it initializes a local SQLite database file called expenses.db and ensures the expenses table exists. The main entry point in main.py registers MCP tools for inserting expenses, fetching expense rows in a date range, and summarizing totals grouped by category. It also registers an MCP resource at expense://categories, which reads directly from categories.json each time it is requested.

Because the data is stored locally and the category resource is file-based, the project stays simple, portable, and easy to modify.

Tech Stack

• Language: Python 3.11+
• Runtime / Framework: FastMCP
• Database: SQLite
• Core library: fastmcp

Project Structure

main.py          MCP server entry point and expense tools
categories.json  Category and subcategory taxonomy
expenses.db      Local SQLite database file
pyproject.toml   Project metadata and dependency definition

Installation

Make sure you have Python 3.11 or later installed.

Clone the repository and install dependencies:

pip install fastmcp

If you are using a virtual environment, activate it first.

Running the server

Start the MCP server with:

python main.py

This will launch the FastMCP server and initialize the local database if it does not already exist.

Available MCP Tools

add_expense(date, amount, category, subcategory="", note="")

Adds a new expense record to the database.

Example:

{
  "date": "2026-07-14",
  "amount": 24.5,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch"
}

list_expenses(start_date, end_date)

Returns all expense entries within the inclusive date range, ordered by record ID.

Example:

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

summarize(start_date, end_date, category=None)

Returns total spending grouped by category for the given date range. If category is provided, the summary is filtered to that category.

Example:

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

Available Resource

expense://categories

Returns the category taxonomy defined in categories.json as JSON.

This file includes high-level categories such as:

• food
• transport
• housing
• utilities
• health
• education
• family_kids
• entertainment
• shopping
• subscriptions
• personal_care
• gifts_donations
• finance_fees
• business
• travel
• home
• pet
• taxes
• investments
• misc

Each category includes a set of subcategories for more specific expense classification.

Category File

You can customize the available categories by editing categories.json.

Because the resource reads the file fresh every time it is accessed, you do not need to restart the server after changing categories.

Example Usage

A typical flow looks like this:

1. Start the MCP server
2. Add expense entries with add_expense
3. Query records with list_expenses
4. Generate spending insights with summarize
5. Use expense://categories to drive category selection in a client

Notes

• Expenses are stored in a local SQLite database file named expenses.db
• Dates are expected to be passed in a consistent text format, such as YYYY-MM-DD
• The project is intentionally minimal and may be extended with validation, editing, deletion, authentication, or richer reporting in the future

Getting Started

If you are building an MCP-compatible expense assistant, this server is a compact starting point that you can run locally and extend as needed.