Expense Tracker MCP

A personal expense tracking server built with FastMCP that exposes tools and resources via the Model Context Protocol (MCP). Connect it to any MCP-compatible AI client (Claude Desktop, Cursor, etc.) to log, query, and summarize your spending through natural language.

Features

• Add expenses — record date, amount, category, optional subcategory, and a free-text note
• List expenses — retrieve all entries within any date range
• Summarize spending — aggregate totals by category, optionally filtered to a single category
• Category reference — a live-reloadable resource (expense://categories) exposes all valid categories and subcategories so the AI always suggests valid values

Tech Stack

Component	Technology
MCP framework	FastMCP ≥ 3.1
Database	SQLite (file-based, zero config)
Runtime	Python ≥ 3.12

Project Structure

expense-tracker-mcp/
├── main.py            # MCP server — tools & resource definitions
├── categories.json    # Category / subcategory taxonomy (editable at runtime)
├── expenses.db        # SQLite database (auto-created on first run)
├── pyproject.toml     # Project metadata & dependencies
└── README.md

Getting Started

1. Clone and install dependencies

git clone <repo-url>
cd expense-tracker-mcp

uv sync

2. Run the server

uv run python main.py

The server starts and listens for MCP connections. The expenses.db SQLite file is created automatically next to main.py on the first run.

3. Connect to an MCP client

Claude Desktop

Add the following block to your claude_desktop_config.json:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/expense-tracker-mcp", "python", "main.py"]
    }
  }
}

Cursor / other clients

Follow your client's MCP configuration guide, pointing the command at the same Python executable and main.py.

MCP Tools

add_expense

Add a new expense entry.

Parameter	Type	Required	Description
date	string	Yes	ISO 8601 date, e.g. 2026-03-09
amount	number	Yes	Expense amount (positive value)
category	string	Yes	Top-level category (see categories below)
subcategory	string	No	Subcategory within the category
note	string	No	Free-text description

Returns: { "status": "ok", "id": <inserted row id> }

---

list_expenses

Retrieve all expenses within a date range (inclusive).

Parameter	Type	Required	Description
start_date	string	Yes	ISO 8601 start date
end_date	string	Yes	ISO 8601 end date

Returns: Array of expense objects with fields id, date, amount, category, subcategory, note.

---

summarize

Aggregate total spending by category within a date range.

Parameter	Type	Required	Description
start_date	string	Yes	ISO 8601 start date
end_date	string	Yes	ISO 8601 end date
category	string	No	Filter to a single category

Returns: Array of { "category": "...", "total_amount": <number> } objects, ordered alphabetically.

MCP Resource

expense://categories

Returns the full categories.json file as application/json. The file is read from disk on every request, so you can add or rename categories without restarting the server. The AI uses this resource to suggest valid category and subcategory values when logging expenses.

Categories

The taxonomy ships with 18 top-level categories:

Category	Example Subcategories
food	groceries, dining_out, delivery_fees
transport	fuel, public_transport, cab_ride_hailing
housing	rent, repairs_service, furnishing
utilities	electricity, internet_broadband, mobile_phone
health	medicines, doctor_consultation, fitness_gym
education	books, courses, online_subscriptions
family_kids	school_fees, daycare, toys_games
entertainment	movies_events, streaming_subscriptions, games_apps
shopping	clothing, electronics_gadgets, home_decor
subscriptions	saas_tools, cloud_ai, music_video
personal_care	salon_spa, grooming, cosmetics
gifts_donations	gifts_personal, charity_donation, festivals
finance_fees	bank_charges, interest, brokerage
business	hosting_domains, marketing_ads, contractor_payments
travel	flights, hotels, visa_passport
home	household_supplies, cleaning_supplies, small_repairs
pet	food, vet, grooming
taxes	income_tax, gst, filing_fees

Every category also accepts "other" as a catch-all subcategory. Edit categories.json freely to add your own.

Example Prompts

Once connected to an AI client:

Add an expense: ₹450 on groceries today

List all my expenses for February 2026

Summarize my spending between 2026-01-01 and 2026-03-09

How much did I spend on food and transport this month?

Development

Inspect with MCP Inspector

FastMCP 3.x ships with an interactive inspector. Launch it with:

uv run fastmcp dev inspector main.py

This opens the MCP Inspector UI in your browser so you can call tools and browse resources interactively without a full AI client.

Reset the database

The schema is initialised automatically via init_db() on first run. To wipe all data:

rm expenses.db