DaniManas/exp-tracker-local-mcp

exp-tracker-local-mcp

A Model Context Protocol (MCP) server that records personal expenses in SQLite and exposes FastMCP tools for adding, listing, updating, deleting, and analyzing those expenses—including budgeting utilities and CSV export. Follow the steps below to recreate the project and run the server locally.

Prerequisites

• macOS, Linux, or Windows with Python 3.12+
• uv package manager (recommended)
• Git and a code editor (VS Code is used in the walkthrough)

Step-by-Step Setup

1. Install uv

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Create or clone the project folder

   git clone https://github.com/<your-user>/expense-tracker-mcp-server.git
   cd expense-tracker-mcp-server
   

   Building from scratch? Create a new folder (for example fastmcp-demo-server) and run the remaining steps inside it.

3. Open the folder in VS Code

   code .
   

4. Open a terminal inside VS Code (⌃ on macOS / Ctrl on Windows or Linux).

5. Initialize the uv environment

   • For a fresh folder: uv init .
   • For this repository: uv sync

6. Add FastMCP (only needed if you ran uv init)

   uv add fastmcp
   

7. Verify FastMCP is available

   uv run fastmcp --version
   

8. Review the server code

   • main.py defines the FastMCP server, SQLite schema, and MCP tools.
   • categories.json exposes expense categories through the expense://categories resource.

Running and Testing

• Development mode with auto-reload

  uv run fastmcp dev main.py
  

• Regular run

  uv run fastmcp run main.py
  

• Direct Python run

  uv run main.py
  

MCP Inspector

1. Install the MCP Inspector.
2. Configure the connection:
   • Transport Type: STDIO
   • Command: uv
   • Arguments: run /absolute/path/to/main.py --no-banner
   • Working Directory: repository root
3. Click Connect and invoke the tools interactively.

Claude Desktop

Add the server so Claude can call it:

uv run fastmcp install claude-desktop main.py

This command injects the server definition into claude_desktop_config.json. Restart Claude Desktop afterwards.

Available Tools

• add_expense(date, amount, category, subcategory="", note="")
• list_expenses(start_date, end_date)
• update_expense(id, date=None, amount=None, category=None, subcategory=None, note=None)
• delete_expense(id)
• summarize(start_date, end_date, category=None)
• get_statistics(start_date, end_date, category=None) – returns count, totals, min/max, and average.
• get_spending_trends(start_date, end_date, group_by="month", category=None) – shows aggregated spend grouped by day/week/month/year.
• export_to_csv(start_date, end_date, file_path) – writes filtered expenses to a CSV file.
• set_budget(category, amount, start_date, end_date) – creates or updates a category budget for a specific period.
• check_budget_status(category, start_date, end_date) – compares actual spend vs. the stored budget.
• Resource expense://categories returns the JSON in categories.json.

Project Files

main.py          # FastMCP server implementation
categories.json  # Expense categories served as an MCP resource
expenses.db      # SQLite database (created on first run) with expenses and budgets tables
pyproject.toml   # uv project metadata and dependencies
uv.lock          # Locked dependency versions
README.md        # This guide

Database Schema

CREATE TABLE expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT DEFAULT '',
    note TEXT DEFAULT ''
);

CREATE TABLE budgets(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT NOT NULL,
    amount REAL NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT NOT NULL,
    UNIQUE(category, start_date, end_date)
);

Next Steps

• Customize categories.json with your own budgeting taxonomy.
• Add new tools (CSV import, reporting, etc.) to main.py as needed.
• Integrate the server with additional MCP-compatible clients or workflows.