Expenses Tracker MCP Server Client

A modern expense tracking system built with FastMCP 2.0 and Streamlit, featuring Google Gemini 2.5 Flash AI integration for intelligent natural language expense processing.

✨ Features

🏦 MCP Server (FastMCP 2.0)

• Modern MCP Implementation: Latest FastMCP 2.0 with HTTP transport
• SQLite Database: Robust local storage with proper indexing
• Smart Categories: Predefined categories with intelligent subcategory mapping
• Date Range Filtering: Flexible date-based expense queries
• Currency Support: Native support for Indian Rupees (₹)
• AI-Powered Analysis: Gemini integration for expense insights

🤖 AI Integration (Google Gemini 2.5 Flash)

• Natural Language Processing: Parse expenses like "I spent 250 rupees on breakfast today"
• Smart Date Recognition: Understands "today", "yesterday", "last week", "this month"
• Intelligent Categorization: Auto-categorizes expenses from context
• Conversational Interface: Chat-style interaction for expense management
• Context-Aware Responses: AI responses based on your actual expense data

💻 Streamlit Web Client

• Modern Chat Interface: WhatsApp-style conversation UI
• Real-time Processing: Instant expense entry and retrieval
• Dynamic Date Calculations: Automatic date range calculations
• LangGraph Agent: Advanced AI agent with tool orchestration
• Error Handling: Robust error handling with user-friendly messages

🎯 Smart Features

• Week Calculation: Proper Monday-to-Sunday week definitions
• Table Formatting: Beautiful expense tables with category breakdowns
• Quick Commands: Sidebar with example queries
• Session Persistence: Chat history maintained across interactions

🚀 Quick Start

1. Prerequisites

# Ensure you have Python 3.11+ installed
python --version

# Create virtual environment (recommended)
python -m venv .venv

# Activate virtual environment
# Windows:
.\.venv\Scripts\Activate.ps1
# Linux/Mac:
source .venv/bin/activate

2. Installation

# Install dependencies using uv (faster) or pip
uv pip install -r requirements.txt
# OR
pip install -r requirements.txt

3. Configuration

# Set your Google Gemini API key
# Get your key from: https://aistudio.google.com/app/apikey
set GOOGLE_API_KEY=your_actual_api_key_here
# OR Linux/Mac:
export GOOGLE_API_KEY=your_actual_api_key_here

4. Start the System

# Terminal 1: Start MCP Server
python server.py

# Terminal 2: Start Streamlit Client (in virtual environment)
.\.venv\Scripts\Activate.ps1
streamlit run client.py

5. Access the Applications

• Streamlit Chat Interface: http://localhost:8501
• MCP Server: http://localhost:8000/mcp (for other MCP clients)

📖 Usage Guide

Streamlit Chat Interface

1. Natural Language Expense Entry:

   "I spent 250 rupees on breakfast today"
   "Add ₹500 for groceries yesterday"
   "Paid ₹2000 for cab to native place on Oct 3"
   

2. Smart Date Queries:

   "Show my expenses for last 10 days"
   "Summarize all my transactions for this week"
   "What did I spend this month?"
   "List expenses from last 30 days in tabular fashion"
   

3. Category Analysis:

   "Analyze my spending patterns"
   "Show category breakdown for food expenses"
   "How much did I spend on transport?"
   

4. Conversational Interface:

   • Type naturally in the chat box
   • Get instant responses with formatted tables
   • View category breakdowns and totals
   • Historical context maintained in chat

Example Interactions

Adding an Expense:

User: "I spent 150 rupees on cab fare today"
Assistant: ✅ Added expense: ₹150 for transport (cab) on 2025-10-07

Viewing Expenses:

User: "Show my last 7 days expenses"
Assistant: [Displays formatted table with 7 days of transactions]

Direct MCP Client Usage

Connect to the MCP server directly:

import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        # Add an expense
        result = await client.call_tool("add_expense", {
            "date": "2025-10-07",
            "amount": 250.0,
            "category": "food",
            "subcategory": "breakfast",
            "note": "Morning breakfast"
        })
        
        # List expenses for date range
        result = await client.call_tool("list_expenses", {
            "start_date": "2025-09-27",
            "end_date": "2025-10-07"
        })
        
        # Get expense summary
        result = await client.call_tool("get_expense_summary", {})
        
        # AI analysis
        result = await client.call_tool("analyze_expenses_with_ai", {
            "query": "What are my spending patterns this month?"
        })

asyncio.run(main())

🛠️ MCP Integration

FastMCP 2.0 Server

The system runs as a complete MCP server using FastMCP 2.0 with HTTP transport:

# The server runs automatically when you start server.py
# Accessible at: http://localhost:8000/mcp

Available MCP Tools

• add_expense(date, amount, category, subcategory, note): Add new expense with validation
• list_expenses(start_date?, end_date?, category?): List expenses with optional filtering
• get_expense_summary(start_date?, end_date?, category?): Get category summaries and totals
• delete_expense(expense_id): Remove expense by ID
• analyze_expenses_with_ai(query): AI-powered expense analysis using Gemini

Tool Examples

# Add expense
await client.call_tool("add_expense", {
    "date": "2025-10-07",
    "amount": 250.0,
    "category": "food",
    "subcategory": "breakfast",
    "note": "Breakfast at cafe"
})

# List last 10 days
await client.call_tool("list_expenses", {
    "start_date": "2025-09-27",
    "end_date": "2025-10-07"
})

# Get summary for current month
await client.call_tool("get_expense_summary", {
    "start_date": "2025-10-01",
    "end_date": "2025-10-07"
})

📁 Project Structure

MCP/
├── server.py              # FastMCP 2.0 server with expense tools
├── client.py              # Streamlit chat interface with LangGraph agent
├── uv.lock               # Dependency lock file
├── data/
│   ├── expenses.db       # SQLite database with expenses
│   └── categories.json   # Category definitions
├── pyproject.toml         # Python dependencies and project metadata
└── README.md            

🔧 Configuration

Environment Variables

# Required for AI features
GOOGLE_API_KEY=your_gemini_api_key_here

# Optional: Custom MCP server URL for client
EXPENSE_MCP_URL=http://localhost:8000/mcp

Categories System

The system uses a hierarchical category structure defined in data/categories.json:

{
  "categories": {
    "food": ["groceries", "dining", "breakfast", "lunch", "dinner"],
    "transport": ["cab", "bus", "train", "fuel", "public_transport"],
    "shopping": ["clothing", "electronics", "household"],
    "healthcare": ["medical", "pharmacy", "fitness"],
    "utilities": ["electricity", "water", "internet", "phone"],
    "entertainment": ["movies", "games", "books"],
    "education": ["courses", "materials", "books"],
    "housing": ["rent", "maintenance", "utilities"],
    "other": ["miscellaneous"]
  }
}

Smart Categorization

The AI automatically maps natural language to categories:

• "breakfast", "lunch", "dinner" → food
• "cab", "taxi", "uber", "bus" → transport
• "medicine", "doctor", "pharmacy" → healthcare

🚦 Running Options

Standard Setup (Recommended)

# Terminal 1: MCP Server
python server.py

# Terminal 2: Streamlit Client (ensure virtual environment is active)
.\.venv\Scripts\Activate.ps1
streamlit run client.py

Development Mode

# Run server with debug output
python server.py --debug

# Run Streamlit on custom port
streamlit run client.py --server.port 8502

🔍 MCP Server Endpoints

MCP Protocol

• POST /mcp - Main MCP endpoint for tool calls
• GET /mcp - MCP capabilities and tool listings

Available Tools via MCP

1. add_expense - Add new expense entry
2. list_expenses - List expenses with optional date/category filters
3. get_expense_summary - Get aggregated expense summaries
4. delete_expense - Remove expense by ID
5. analyze_expenses_with_ai - AI-powered expense analysis

Health Check

• Server runs on http://localhost:8000
• MCP endpoint: http://localhost:8000/mcp

🧠 AI Features (Google Gemini 2.5 Flash)

Natural Language Processing

Transform conversational text into structured expense data:

• Input: "I spent 250 rupees on breakfast today"
• Processing: Extracts amount (250), category (food), subcategory (breakfast), date (today)
• Output: Structured expense entry with ₹250, food category, 2025-10-07 date

Smart Date Recognition

Understands various date expressions:

• "today", "yesterday" → Exact dates
• "last 10 days", "this week" → Date ranges with proper calculations
• "this month", "last month" → Monthly boundaries
• Dynamic calculation using Python datetime

Intelligent Categorization

AI maps context to expense categories:

• "breakfast", "lunch", "dinner" → food category
• "cab", "taxi", "bus", "train" → transport category
• "medicine", "doctor" → healthcare category
• Falls back to "other" for unknown items

Conversational Analysis

Ask natural questions about spending:

• "Show my expenses for last 10 days in tabular fashion"
• "How much did I spend on transport this month?"
• "Analyze my spending patterns"
• "What's my category breakdown?"

Context-Aware Responses

• Remembers conversation history
• Provides formatted tables with ₹ currency
• Shows category breakdowns and percentages
• Calculates totals and trends automatically

🐛 Troubleshooting

Common Issues

1. Streamlit "ModuleNotFoundError":

   # Ensure you're in the virtual environment
   .\.venv\Scripts\Activate.ps1
   streamlit run client.py
   

2. MCP Server not starting:

   # Check if port 8000 is in use
   netstat -an | findstr :8000
   
   # Kill existing processes
   taskkill /f /im python.exe
   

3. AI features not working:

   • Verify GOOGLE_API_KEY environment variable
   • Check API key at https://aistudio.google.com/app/apikey
   • Ensure internet connection for Gemini API

4. Date filtering issues:

   • Check system date/time settings
   • Verify date calculations in debug output
   • Use python quick_test.py to test MCP tools directly

5. Tool parameter errors:

   # Test MCP server tools directly
   python quick_test.py
   
   # Check server logs for validation errors
   

Health Checks

# Test MCP server
python quick_test.py

# Check database
python view_database.py

# Verify Streamlit client
streamlit run client.py --server.headless true

Debug Mode

# Run with verbose output
python server.py --verbose

# Check Streamlit logs in terminal
# Look for "Found X tools from MCP server" message

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

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature-name
3. Make changes and test thoroughly
4. Submit pull request with description

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP: For the excellent MCP framework
• FastAPI: For the robust web framework
• Google Gemini: For the powerful AI capabilities
• Rich: For the beautiful CLI interface

🎯 Key Features Demonstrated

MCP Integration Excellence

• ✅ FastMCP 2.0 - Latest MCP framework with HTTP transport
• ✅ Tool Orchestration - 5 expense management tools
• ✅ Parameter Validation - Robust input validation and error handling
• ✅ Async Operations - Non-blocking expense operations

AI Integration Mastery

• ✅ Google Gemini 2.5 Flash - Latest AI model integration
• ✅ LangGraph Agent - Advanced agent with React pattern
• ✅ Natural Language - Conversational expense entry
• ✅ Context Awareness - Chat history and session memory

Modern Web Interface

• ✅ Streamlit Chat UI - Modern conversational interface
• ✅ Real-time Processing - Instant AI responses
• ✅ Dynamic Date Calculations - Smart date range handling
• ✅ Currency Support - Native Indian Rupees (₹) formatting

🏆 Technical Achievements

This project demonstrates:

• MCP Server Development using FastMCP 2.0
• AI Agent Architecture with LangGraph and LangChain
• Natural Language Processing for expense parsing
• Modern Web UI with Streamlit chat interface
• Database Management with SQLite and async operations
• Error Handling and user experience optimization

---