---

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: CRUD operations for expenses with categories, tags, and payment methods.
• ✅ Income & Cashflow: Log earnings and analyze net savings/savings rates.
• ✅ Recurring Engine: Intelligent frequency logic (daily, weekly, monthly, yearly) to auto-generate bills.
• ✅ Smart Budgeting: Set limits per category and get status reports (OK, WARNING, OVER BUDGET).
• ✅ Asynchronous Performance: Built with aiosqlite for non-blocking database operations.
• ✅ Flexible Metadata: In-memory management of categories and payment methods.
• ✅ Zero-Setup Database: SQLite database initializes automatically in the system's temporary directory.

---

🏗️ Architecture

AdvancedExpenseTracker
│
├── server.py          # MCP server implementation (Async)
├── README.md          # Documentation
└── [System Temp]      # expenses.db is stored in your OS temp folder

---

📦 Tech Stack

• Python 3.10+
• FastMCP: High-level MCP framework.
• aiosqlite: Asynchronous interface for SQLite.
• sqlite3: Used for initial synchronous database setup.
• uv: (Recommended) For fast dependency management.

---

⚙️ Installation (using uv)

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️⃣ Test Run

You can verify the server starts correctly:

uv run fastmcp run server.py --transport http --host 0.0.0.0 --port 8000

For testing open diffrent terminal and run:

uv run fastmcp dev server.py

Note: The database is created at TEMP_DIR/expenses.db. The exact path is printed to the console on startup.

---

🔌 Configuration (Connect to AI)

Since this server is configured to use SSE (Server-Sent Events) on port 8000, you can connect to it as a remote resource.

Option A: Claude Desktop App

Add this to your claude_desktop_config.json:

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

Option B: Cursor (IDE)

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

---

🧠 MCP Capabilities

📌 Expense Management

• add_expense: Add a new transaction (date, amount, category, etc.).
• update_expense: Modify existing entries by ID.
• delete_expense: Permanently remove an entry.
• list_expenses: Range-based filtering by date and category.
• search_expenses: Full-text search across notes, tags, and categories.

💰 Income & Cashflow

• add_income: Log salary, dividends, or freelance earnings.
• get_cashflow: Get a summary of Income vs. Expenses and the current savings rate.

🔁 Recurring Expenses Engine

• add_recurring_expense: Create templates for bills (e.g., "Netflix", "Rent").
• process_recurring_expenses: Run this to "materialize" templates into actual expense entries up to a specific date.

📉 Budgeting & Analytics

• set_monthly_budget: Define a spending limit for a specific category.
• get_budget_report: Compare actual spending against limits for any month (YYYY-MM).

🧾 Metadata & Resources

• Resource (expense://metadata): The AI can read this to see the current list of valid categories and payment methods.
• manage_metadata: Add or remove categories/methods during the current session.

---

⚠️ Important Notes

1. Database Persistence: The database is stored in your system's temporary directory. While it persists across script restarts, it may be cleared by your OS if you perform a disk cleanup or system reboot (depending on OS settings).
2. Metadata Persistence: Changes made via manage_metadata are in-memory only. To permanently add a category, edit the GLOBAL_METADATA dictionary in server.py.
3. Dates: Always use the YYYY-MM-DD format for dates and YYYY-MM for budget reports.

---

📜 License

MIT License.

---

🙌 Author

Anubhab Das