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

2. Set up environment variables:
```bash
# Create .env file
ANTHROPIC_API_KEY=your_claude_api_key
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password
IMAP_SERVER=imap.gmail.com
```

3. For Modal deployment (optional):
```bash
modal token new
modal deploy modal_deployment.py
```

## Usage

### Local Development

Run the Gradio interface locally:
```bash
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
```dockerfile
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