💰 Expense Tracker MCP Server

A powerful, AI-ready expense tracking system built with FastMCP (Model Context Protocol) that integrates seamlessly with Claude AI and other LLM applications.

🎯 Status: Production-Ready | 📊 Database: SQLite | 🚀 Framework: FastMCP 3.4.2

---

✨ Features

🎯 Core Expense Management

• ✅ Add Expenses - Track daily spending with category, subcategory, and notes
• ✅ List Expenses - Query expenses by date range
• ✅ Summarize - Category-wise expense breakdown with totals

💰 Budget Management

• ✅ Set Budget - Define monthly budgets per category
• ✅ Check Budget Status - Real-time budget vs actual spending with 🔴🟡🟢 status indicators
• ✅ Budget Alerts - Automatic warnings at 80% budget usage

📊 Analytics & Insights

• ✅ Spending Trends - Weekly trend analysis (last 30 days)
• ✅ Advanced Analytics - Highest/lowest expenses, median, averages per category
• ✅ Smart Insights - AI-generated spending patterns and recommendations
• ✅ Monthly Reports - Comprehensive month-end summaries

🔄 Recurring Expenses

• ✅ Add Recurring Expenses - Subscriptions, rent, bills (daily/weekly/monthly/yearly)
• ✅ List Recurring - View all active subscriptions with estimated monthly cost

🎯 Savings Goals

• ✅ Create Savings Goals - Vacation, emergency fund, new gadgets, etc.
• ✅ Track Progress - Update and monitor goal achievements
• ✅ View All Goals - Dashboard with progress percentages and deadlines

🔮 Forecasting

• ✅ Expense Forecast - Predict next month expenses (70% historical + 30% recurring)
• ✅ Spending Prediction - AI-powered forecasting based on patterns

---

🛠️ Installation

Prerequisites

• Python 3.8+
• pip or uv (recommended)

Step 1: Clone Repository

git clone https://github.com/mhd-faraz/Expense-Tracker-MCP.git
cd Expense-Tracker-MCP

Step 2: Create Virtual Environment

# Using uv (faster)
uv venv
source .venv/bin/activate

# Or using Python venv
python3 -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

uv add fastmcp aiosqlite

Step 4: Run Server

python3 main.py

Expected Output:

✅ Database initialized with all tables - write access confirmed
INFO: Uvicorn running on http://0.0.0.0:8321/mcp (Press CTRL+C to quit)

---

📖 Usage

Option 1: MCP Inspector (Testing)

1. Open browser: http://localhost:8321/mcp/inspector
2. Select tool from dropdown
3. Fill parameters
4. Click "Run Tool"

Example:

{
  "date": "2026-06-19",
  "amount": 450,
  "category": "Food & Dining",
  "subcategory": "Restaurant",
  "note": "Lunch with team"
}

Option 2: Claude Desktop (Production)

1. Connect to this MCP server in Claude Desktop
2. Use natural language:

"Add an expense of ₹3000 for groceries today"
"Show my spending trends for the last 30 days"
"What's my budget status for this month?"
"Create a savings goal of ₹50000 for vacation by December"
"Forecast my next month expenses"

Claude will automatically call the appropriate tools and update your database!

Option 3: Python Script

import aiosqlite
import asyncio

async def add_expense():
    async with aiosqlite.connect("/tmp/expenses.db") as db:
        await db.execute(
            "INSERT INTO expenses(date, amount, category, note) VALUES (?,?,?,?)",
            ("2026-06-19", 450, "Food & Dining", "Lunch")
        )
        await db.commit()

asyncio.run(add_expense())

---

🗄️ Database Schema

expenses

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 '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

budgets

CREATE TABLE budgets(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    category TEXT NOT NULL,
    amount REAL NOT NULL,
    month TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(category, month)
)

recurring_expenses

CREATE TABLE recurring_expenses(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    frequency TEXT NOT NULL,
    start_date TEXT NOT NULL,
    end_date TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

savings_goals

CREATE TABLE savings_goals(
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    goal_name TEXT NOT NULL,
    target_amount REAL NOT NULL,
    current_amount REAL DEFAULT 0,
    deadline TEXT NOT NULL,
    category TEXT DEFAULT 'Savings',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

Database Location: /tmp/expenses.db (macOS/Linux)

---

🔧 Available Tools (13 Total)

#	Tool	Purpose	Parameters
1	add_expense()	Add new expense	date, amount, category, subcategory, note
2	list_expenses()	Query expenses	start_date, end_date
3	summarize()	Category summary	start_date, end_date, category
4	set_budget()	Set monthly budget	category, amount, month
5	check_budget_status()	Budget tracking	month
6	add_recurring_expense()	Add subscription	name, amount, category, frequency, start_date
7	list_recurring_expenses()	View subscriptions	(no params)
8	create_savings_goal()	New savings target	goal_name, target_amount, deadline, category
9	update_savings_goal_progress()	Track progress	goal_id, amount_saved
10	get_savings_goals()	View all goals	(no params)
11	get_spending_trends()	Weekly trends	days
12	get_expense_analytics()	Detailed stats	start_date, end_date
13	forecast_expenses()	Next month prediction	months_ahead
14	get_smart_insights()	AI recommendations	(no params)
15	generate_monthly_report()	Monthly summary	month

---

📊 Example Outputs

Budget Status:

Category          Budget    Spent     Remaining  Usage%   Status
Food & Dining     ₹5000     ₹2300     ₹2700      46.0%    🟢 OK
Transportation    ₹3000     ₹1200     ₹1800      40.0%    🟢 OK
Bills & Utilities ₹4000     ₹2500     ₹1500      62.5%    🟢 OK

Smart Insights:

🎯 TOP SPENDING
   Food & Dining is your biggest expense (₹2300) - 35.2% of budget

📊 FREQUENCY
   Transportation has most transactions (4 times). Small amounts add up!

📈 DAILY PACE
   You're spending ₹473 per day on average

💡 OPTIMIZATION
   You have 3 categories eating >20% of budget. Consider consolidating!

Forecast:

Category          Predicted    vs Last Month
Bills & Utilities ₹6429.70     ↑ +157.2%
Groceries         ₹2450.00     ↓ -30.0%
Food & Dining     ₹2060.00     ↓ -10.4%

---

🚀 Connect to Claude Desktop

Step 1: Get Server URL

http://0.0.0.0:8321/mcp

Step 2: Add to Claude Settings

In Claude Desktop, go to Settings → Connected Servers:

{
  "mcpServers": {
    "expense-tracker": {
      "command": "python3",
      "args": ["/path/to/main.py"],
      "type": "stdio"
    }
  }
}

Step 3: Start Using!

Now tell Claude:

"I spent ₹3000 on groceries today"
"Show my monthly budget status"
"Create a savings goal for my vacation"
"What are my spending trends?"

---

📁 Project Structure

Expense-Tracker-MCP/
├── main.py                      # Main MCP server (13 tools)
├── test_expense_tracker.py      # Complete test suite
├── categories.json              # Category definitions
├── .gitignore                   # Git ignore rules
├── README.md                    # This file
└── .venv/                       # Virtual environment

---

🧪 Testing

Run the complete test suite:

python3 test_expense_tracker.py

Output includes:

• ✅ 10 sample expenses
• ✅ 5 budget configurations
• ✅ 5 recurring expenses
• ✅ 4 savings goals
• ✅ All 15 tools tested
• ✅ Formatted analytics and reports

---

🔐 Security & Best Practices

• ✅ Database uses WAL mode for concurrent access
• ✅ Async/await for non-blocking operations
• ✅ Input validation on all parameters
• ✅ Proper error handling with meaningful messages
• ✅ Database transactions for data integrity

---

📈 Tech Stack

• Framework: FastMCP 3.4.2
• Database: SQLite 3
• Async Runtime: asyncio + aiosqlite
• Server: Uvicorn
• Language: Python 3.12+

---

🎯 Use Cases

1. Personal Finance Tracking - Daily expense logging
2. Budget Planning - Monthly budget management
3. Goal Tracking - Savings and financial targets
4. Spending Analysis - Trend analysis and forecasting
5. AI Integration - Natural language expense tracking via Claude

---

📝 Categories Supported

Food & Dining      Bills & Utilities    Healthcare
Transportation     Entertainment        Travel
Shopping           Education            Business
Subscriptions      Groceries           Personal Care
Other

---

🤝 Contributing

This is a portfolio project. Feel free to fork and extend!

Ideas for enhancement:

• Export to CSV/PDF
• Multi-user support
• Cloud sync
• Mobile app integration
• Advanced ML predictions

---

📄 License

MIT License - Feel free to use and modify!

---

👨‍💻 Author

Faraz - CS Engineering Graduate (2025)
Portfolio: faraz-portfolio-ivvo-xi.vercel.app
GitHub: @mhd-faraz

---

🙋 FAQ

Q: Database file empty?
A: Database files are binary. Use list_expenses() tool to verify data exists.

Q: Can I use this without Claude Desktop?
A: Yes! Use MCP Inspector or call tools directly via Python.

Q: How do I reset all data?
A: Delete /tmp/expenses.db and restart server.

Q: Can I host this online?
A: Yes! Deploy to MCPCloud, Vercel, or Railway.

---

🚀 Next Steps

1. ✅ Clone this repo
2. ✅ Run python3 main.py
3. ✅ Open http://localhost:8321/mcp/inspector
4. ✅ Test a tool
5. ✅ Connect to Claude Desktop
6. ✅ Start tracking expenses with AI!

---

Happy Expense Tracking! 💰✨