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

Related MCP server: Trackor

Tech Stack

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.

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

list_expenses

Retrieve all expenses within a date range (inclusive).

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

summarize

Aggregate total spending by category within a date range.

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:

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