AdvancedExpenseTracker (FastMCP)

An AI-powered Expense & Budget Management MCP Server built using FastMCP, SQLite, and Python.
This project exposes structured financial tools (expenses, income, budgets, recurring bills, analytics) that can be used by an LLM (like Claude Desktop or Cursor) as a personal financial advisor.

---

🚀 Features Overview

• ✅ Expense Tracking: Categories, subcategories, tags, notes, and payment methods.
• ✅ Income & Cashflow: Log earnings and analyze net savings in real-time.
• ✅ Recurring Engine: Auto-generate daily, weekly, monthly, or yearly bills.
• ✅ Smart Budgeting: Set limits per category and get "Over Budget" warnings.
• ✅ Search & Filtering: Find transactions by note, tag, or amount.
• ✅ Metadata Management: Dynamic control over valid categories & payment methods.
• ✅ Zero-Setup Database: SQLite database initializes automatically.

---

🏗️ Architecture

AdvancedExpenseTracker
│
├── expenses.db        # SQLite database (auto-created on first run)
├── metadata.json      # Categories & payment methods (auto-created)
├── main.py            # MCP server implementation
└── README.md

---

📦 Tech Stack

• Python 3.10+
• FastMCP (The only external dependency)
• SQLite (Built-in, serverless storage)
• uv (For ultra-fast dependency management)

---

⚙️ Installation (using uv)

This project is designed to run instantly with uv. You do not need to manually create virtual environments.

1️⃣ Install uv (if not installed)

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2️⃣ Clone the Repository

git clone <your-repo-url>
cd AdvancedExpenseTracker

3️⃣ Test Run

You can verify the script works without installing anything globally:

uv run --with fastmcp main.py

On the first run, this will create expenses.db and metadata.json automatically.

---

🔌 Configuration (Connect to AI)

To use this with Claude Desktop or Cursor, you need to tell them where the script is.

Option A: Claude Desktop App

1. Open your config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the following (Replace /ABSOLUTE/PATH/TO/ with your real file path):

{
  "mcpServers": {
    "finance": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "/ABSOLUTE/PATH/TO/main.py"
      ]
    }
  }
}

Option B: Cursor (IDE)

1. Go to Cursor Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Name: Expense Tracker
4. Type: command
5. Command: uv run --with fastmcp /ABSOLUTE/PATH/TO/main.py

---

🧠 MCP Capabilities (Detailed)

📌 Expense Management

➕ Add Expense

add_expense(
  date="2026-01-05",
  amount=250,
  category="Food",
  subcategory="Dining",
  payment_method="Credit Card",
  note="Dinner with friends",
  tags="restaurant,weekend"
)

✏️ Update Expense

Update only the fields you want to change:

update_expense(expense_id=1, amount=300, note="Updated bill amount")

❌ Delete Expense

delete_expense(expense_id=1)

📄 List Expenses

list_expenses(
  start_date="2026-01-01",
  end_date="2026-01-31",
  category="Food",
  limit=50
)

🔍 Search Expenses

Search across category, subcategory, notes, and tags:

search_expenses(query="restaurant")

---

💰 Income & Cashflow

➕ Add Income

add_income(
  date="2026-01-01",
  amount=5000,
  source="Salary",
  note="January Paycheck"
)

📊 Cashflow Analysis

get_cashflow(start_date="2026-01-01", end_date="2026-01-31")

Returns:

{
  "total_income": 5000,
  "total_expenses": 1800,
  "net_savings": 3200,
  "savings_rate": "64.0%"
}

---

🔁 Recurring Expenses Engine

➕ Add Recurring Expense

add_recurring_expense(
  name="Netflix",
  amount=15.99,
  category="Entertainment",
  frequency="monthly",
  start_date="2026-01-01"
)

Supported frequencies: daily, weekly, monthly, yearly.

🔄 Process/Refresh Bills

Run this to generate actual expense entries from your templates:

process_recurring_expenses(target_date="2026-03-31")

---

📉 Budgeting & Alerts

🎯 Set Monthly Budget

set_monthly_budget(category="Food", amount=500)

📑 Budget Report

get_budget_report(month_str="2026-01")

Status logic:

• ✅ OK
• ⚠️ WARNING (>90% used)
• ❌ OVER BUDGET

---

🧾 Metadata Management

📥 Get Metadata (Resource)

The AI reads this to know which categories are allowed.

expense://metadata

➕ Manage Categories/Methods

manage_metadata(action="add", type="categories", value="Education")
manage_metadata(action="remove", type="payment_methods", value="Cash")

---

🤖 Built-in LLM Prompt

🧠 Financial Advisor Prompt

financial_advisor()

This prompt instructs the LLM to:

• Act as a data-driven financial advisor.
• Always validate metadata before logging.
• Prioritize cashflow health and budget warnings.
• Proactively manage recurring subscriptions.

---

🔐 Data Safety

• All data is stored locally in expenses.db.
• No external API calls or cloud syncing.
• To backup your data, simply copy the .db file.

---

📜 License

MIT License – free to use, modify, and distribute.

---

🙌 Author

Anubhab Das