README.md

---
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:
```bash
pip install -r requirements.txt
```

2. Set up environment variables:
```bash
# Create .env file
ANTHROPIC_API_KEY=your_claude_api_key
SAMBANOVA_API_KEY=your_sambanova_api_key  # Optional
EMAIL_USER=your[email protected]
EMAIL_PASS=your_app_password
IMAP_SERVER=imap.gmail.com
```

3. For Modal deployment (recommended for production):

**Quick Setup (Recommended):**
```bash
python setup_modal.py
```

**Manual Setup:**
```bash
# 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:
```bash
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
```python
# 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
```dockerfile
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
- [x] Multi-currency support (USD, INR, EUR, GBP, CAD, AUD, JPY, CNY)
- [ ] Automated bill tracking
- [ ] Enhanced currency conversion features
- [ ] Real-time exchange rate integration