Hugging Face's logo

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

App Files Community
Spend-Analyzer-MCP / README.md
Balamurugan Thayalan
Initial Commit
499796e
preview code
|
raw
history blame
5.8 kB
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

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

  • 📧 Email Processing: Automatically fetch and process bank statements from your email
  • 📄 PDF Upload: Direct upload and analysis of bank statement PDFs
  • 📊 Analysis Dashboard: Interactive charts and financial summaries
  • 🤖 AI Financial Advisor: Chat with Claude for personalized financial advice
  • ⚙️ Settings & Configuration: Customize budgets, email settings, and export options
  • 🔐 Security: Password-protected PDF support and secure email connections

Architecture

The project consists of several key components:

  1. gradio_interface.py - Main web interface built with Gradio
  2. spend_analyzer.py - Core financial analysis engine
  3. email_processor.py - Email and PDF processing functionality
  4. modal_deployment.py - Modal.com cloud deployment configuration
  5. mcp_server.py - Model Context Protocol server implementation

Installation

  1. Install dependencies:
pip install -r requirements.txt
  1. Set up environment variables:
# Create .env file
ANTHROPIC_API_KEY=your_claude_api_key
[email protected]
EMAIL_PASS=your_app_password
IMAP_SERVER=imap.gmail.com
  1. For Modal deployment (optional):
modal token new
modal deploy modal_deployment.py

Usage

Local Development

Run the Gradio interface locally:

python gradio_interface.py

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

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)

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

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/
├── gradio_interface.py      # Main web interface
├── spend_analyzer.py        # Financial analysis engine
├── email_processor.py       # Email/PDF processing
├── modal_deployment.py      # Cloud deployment
├── mcp_server.py           # MCP protocol server
├── 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 7860
CMD ["python", "gradio_interface.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

  • Support for more bank formats
  • Real-time transaction monitoring
  • Mobile app interface
  • Advanced ML-based categorization
  • Integration with financial planning tools
  • Multi-currency support
  • Automated bill tracking