Expense Tracker MCP Server

This project is a Model Context Protocol (MCP) server for managing personal expenses. It exposes tools and a resource that can be used by MCP-compatible clients such as Claude Desktop or the FastMCP inspector.

What it does

The server provides:

• add_expense(date, amount, category, subcategory="", note="") to store a new expense
• list_expenses(start_date, end_date) to retrieve expenses in a date range
• summarize(start_date, end_date, category=None) to group totals by category
• expense://categories as a JSON resource for category definitions

Expenses are stored in a local SQLite database created automatically when the server starts.

Requirements

• Python 3.13 or newer
• uv for dependency and script management

Installation

From the project root:

uv sync

This installs the project and its dependencies from the pyproject.toml file.

Run locally with the MCP inspector

Start the server and inspect it in the FastMCP inspector:

uv run fastmcp dev inspector src/expense_tracker_mcp_server/main.py

This opens the inspector UI and lets you test the tools and resources.

Connect to Claude Desktop

To install the server into Claude Desktop, run:

uv run fastmcp install claude-desktop src/expense_tracker_mcp_server/main.py

On Windows, Claude Desktop may store its config under a packaged-app path. If the default location is not detected, provide it explicitly:

uv run fastmcp install claude-desktop --config-path "C:\Users\<your-user>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude" src/expense_tracker_mcp_server/main.py

Replace <your-user> with your Windows username.

Project structure

src/
  expense_tracker_mcp_server/
    __init__.py
    main.py

• main.py contains the MCP server implementation and tool definitions.
• expenses.db is created automatically at runtime in the package directory.
• categories.json is loaded as the expense://categories resource.

Example usage

Once the server is running, you can call the tools with payloads such as:

{
  "date": "2026-07-31",
  "amount": 42.5,
  "category": "Food",
  "subcategory": "Lunch",
  "note": "Team lunch"
}

Notes

• The SQLite database is local to the project and will be created on first run.
• The categories resource is read from the JSON file each time it is requested, so edits are picked up without restarting the server.