Hugging Face's logo

Spaces:
Agents-MCP-Hackathon
/
Spend-Analyzer-MCP
Sleeping

App Files Community
Spend-Analyzer-MCP / README.md
Balamurugan Thayalan
demo link added
8a7b7d2
preview code
|
raw
history blame contribute delete
8.21 kB

A newer version of the Gradio SDK is available: 5.44.1

Upgrade
metadata
title: Spend Analyzer MCP
emoji: ⚡
colorFrom: yellow
colorTo: pink
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: Finance MCP to Analyze Finance Statement (Email, PDF)

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Spend Analyzer MCP

DEMO : https://youtu.be/juBaOORV4Fc

A comprehensive financial analysis tool that processes bank statements from emails or uploaded PDFs, analyzes spending patterns, and provides AI-powered financial insights through a Model Context Protocol (MCP) interface.

Features

  • 📄 PDF Upload: Direct upload and analysis of bank statement PDFs
  • 📊 Analysis Dashboard: Interactive charts and financial summaries
  • 🤖 AI Financial Advisor: Chat with Claude or SambaNova for personalized financial advice
  • ⚙️ Settings & Configuration: Customize budgets, email settings, and export options
  • 🔐 Security: Password-protected PDF support and secure email connections
  • ☁️ Cloud Deployment: Ready-to-deploy Modal.com configuration
  • 🔌 MCP Integration: Full Model Context Protocol support for external AI systems

Architecture

The project consists of several key components:

  1. app.py - Main web interface built with Gradio (primary application entry point)
  2. spend_analyzer.py - Core financial analysis engine with ML-based insights
  3. email_processor.py - Email and PDF processing with multi-bank support and currency detection
  4. modal_deployment.py - Enhanced Modal.com cloud deployment with dual AI providers
  5. mcp_server.py - Model Context Protocol server implementation
  6. DEPLOYMENT_GUIDE.md - Comprehensive deployment and setup guide

Installation

  1. Install dependencies:
pip install -r requirements.txt
  1. Set up environment variables:
# Create .env file
ANTHROPIC_API_KEY=your_claude_api_key
SAMBANOVA_API_KEY=your_sambanova_api_key  # Optional
[email protected]
EMAIL_PASS=your_app_password
IMAP_SERVER=imap.gmail.com
  1. For Modal deployment (recommended for production):

Quick Setup (Recommended):

python setup_modal.py

Manual Setup:

# Install Modal CLI
pip install modal

# Authenticate
modal token new

# Create secrets (see DEPLOYMENT_GUIDE.md for details)
modal secret create anthropic-api-key ANTHROPIC_API_KEY=your_key
modal secret create sambanova-api-key SAMBANOVA_API_KEY=your_key
modal secret create email-credentials EMAIL_USER=your_email EMAIL_PASS=your_password

# Deploy
modal deploy modal_deployment.py

Usage

Local Development

Run the main Gradio interface locally:

python app.py

The interface will be available at http://localhost:7861

Key Features:

  • Dynamic Currency Detection: Automatically detects currency (USD, INR, EUR, GBP, etc.) from PDF content
  • Multi-Bank Support: Supports HDFC, ICICI, SBI, Axis, Chase, Bank of America, and more
  • Real-time Processing: Upload and analyze actual bank statement PDFs
  • Interactive Dashboard: View spending insights with detected currency formatting

Features Overview

Email Processing Tab

  • Connect to Gmail, Outlook, or Yahoo email
  • Automatically scan for bank statement PDFs
  • Handle password-protected documents
  • Process statements from the last 7-90 days

PDF Upload Tab

  • Direct upload of bank statement PDFs
  • Support for multiple files
  • Password protection handling
  • Instant analysis and processing

Analysis Dashboard

  • Financial summary cards (income, expenses, cash flow)
  • Interactive spending category charts
  • Monthly trend analysis
  • Budget alerts and recommendations
  • Detailed transaction tables

AI Financial Advisor

  • Chat with Claude about your spending patterns
  • Quick question buttons for common queries
  • Contextual responses based on your data
  • Personalized financial recommendations

Settings

  • Budget Settings: Set monthly limits by category
  • Email Settings: Configure email providers and auto-processing
  • Export Settings: Choose data export formats (JSON, CSV, Excel)

AI Providers

The system supports multiple AI providers for financial analysis:

Claude (Anthropic)

  • Model: claude-3-sonnet-20240229
  • Strengths: Advanced reasoning, nuanced financial advice, complex analysis
  • Best for: Detailed financial planning, complex queries, high-quality insights
  • Cost: Higher per token, excellent quality

SambaNova Cloud

  • Model: Meta-Llama-3.1-8B-Instruct
  • Strengths: Fast inference, cost-effective, good general analysis
  • Best for: Quick insights, batch processing, cost-sensitive deployments
  • Cost: Lower per token, good performance

Usage 

# Use Claude for detailed analysis
result = get_ai_analysis(data, "Detailed budget analysis", provider="claude")

# Use SambaNova for quick insights
result = get_ai_analysis(data, "Quick spending summary", provider="sambanova")

MCP Integration

This project implements the Model Context Protocol (MCP) for integration with Claude and other AI systems:

  • Tools: Process statements, analyze PDFs, get AI insights
  • Resources: Access financial data and analysis results
  • Server: Full MCP server implementation for external integrations
  • Webhook: RESTful endpoint for external MCP clients

Security Considerations

  • Email passwords should use app-specific passwords
  • PDF passwords are handled securely in memory
  • No financial data is stored permanently by default
  • All processing can be done locally or in secure cloud environments

Development

Project Structure 

spend-analyzer-mcp-bmt/
├── app.py                   # Main web interface (primary entry point)
├── spend_analyzer.py        # Financial analysis engine
├── email_processor.py       # Email/PDF processing with currency detection
├── modal_deployment.py      # Cloud deployment
├── mcp_server.py           # MCP protocol server
├── gradio_interface.py      # Alternative interface
├── requirements.txt        # Dependencies
└── README.md              # This file

Key Classes

  • SpendAnalyzerInterface: Main Gradio interface controller
  • SpendAnalyzer: Core financial analysis and insights
  • EmailProcessor: Email connection and PDF extraction
  • PDFProcessor: Bank statement PDF parsing
  • MCPServer: Model Context Protocol implementation

Extending the System

  1. Add New Banks: Extend parsing patterns in PDFProcessor
  2. Custom Categories: Modify categorization logic in SpendAnalyzer
  3. New Charts: Add visualization functions to the dashboard
  4. AI Prompts: Enhance Claude integration in modal_deployment.py

Deployment Options

Local Deployment

  • Run directly with Python
  • All processing happens locally
  • Suitable for development and testing

Modal.com Deployment

  • Serverless cloud deployment
  • Scalable processing
  • Integrated with Claude API
  • Production-ready

Docker Deployment 

FROM python:3.11-slim
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
EXPOSE 7861
CMD ["python", "app.py"]

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

This project is open source. Please ensure you comply with your bank's terms of service when processing financial data.

Support

For issues and questions:

  1. Check the existing issues
  2. Create a new issue with detailed information
  3. Include error logs and system information

Roadmap

  • 📧 Email Processing: Automatically fetch and process bank statements from your email (Gmail, YMail, Outlook)
  • Support for more bank formats
  • Real-time transaction monitoring
  • Mobile app interface
  • Advanced ML-based categorization
  • Integration with financial planning tools
  • Multi-currency support (USD, INR, EUR, GBP, CAD, AUD, JPY, CNY)
  • Automated bill tracking
  • Enhanced currency conversion features
  • Real-time exchange rate integration