README.md

---
title: Gmail AI Agent with MCP Integration
emoji: 📧
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "4.19.2"
app_file: app.py
pinned: false
tags:
  - agent-demo-track
  - Agents-MCP-Hackathon
---

# 📧 Gmail AI Agent with MCP Integration

> AI-powered email management using Qwen and Model Context Protocol (MCP)

**Track 3: Agentic Demo**
#agent-demo-track

*Note: A video overview of this application demonstrating its usage and purpose is available at: https://youtu.be/1K3YiV30DMU

## 🌟 Overview

This project combines Qwen AI with the Model Context Protocol (MCP) to create an intelligent email management system. It allows you to interact with your Gmail inbox using natural language, get AI-powered email summaries, and manage your emails through a beautiful web interface.

**Developed for the Gradio Agents & MCP Hackathon 2025**

## ✨ Features

### 📬 Email Management
- **Smart Filtering:** Find emails using Gmail search syntax or natural language
- **Advanced Search:** Filter by sender, subject, attachments, read status
- **Batch Processing:** Handle multiple emails at once
- **Intelligent Triage:** Automatically categorize and prioritize emails

### 🤖 AI Capabilities
- **Email Summarization:** Get concise overviews of your inbox
- **Natural Language Queries:** Ask questions about your emails in plain English
- **Pattern Detection:** Identify important trends and insights
- **Smart Responses:** Generate context-aware email replies
- **Actionable Insights:** Get recommendations based on email content

### 🔌 MCP Integration
- **Tool Integration:** Standard MCP tools for email operations 
- **Resource Access:** Standard resources for inbox, unread, and recent emails
- **Protocol Support:** Full MCP protocol implementation
- **Client-Server Architecture:** Clean separation of concerns

## 🏗️ Architecture

```
┌─────────────────────┐    MCP Protocol    ┌─────────────────────┐
│                     │◄──────────────────►│                     │
│   Gradio Frontend   │                    │   Gmail MCP Server  │
│   (Port 7861)       │                    │   (stdio)           │
│                     │                    │                     │
│  + Qwen AI          │                    │  + Gmail API        │
│  + MCP Client       │                    │  + Email Processing │
│                     │                    │                     │
└─────────────────────┘                    └─────────────────────┘
         │                                           │
         │                                           │
         ▼                                           ▼
   User Interface                              Gmail Account
   + AI Chat                                   + Authentication
   + Email Management                          + Email Data
   + Tool Integration
```

## 🚀 Quick Start

### Prerequisites
- Python 3.8+ installed
- Gmail API credentials (`credentials.json`)
- Modal account for Qwen AI deployment

### Step 1: Install Dependencies
```bash
# Clone the repository
git clone <repository-url>
cd <repository-directory>

# Install requirements
pip install -r requirements.txt
```

### Step 2: Set Up Environment Variables
Create a `.env` file in the project directory:
```
# Gmail API Configuration
GMAIL_CLIENT_ID=your_gmail_client_id_here
GMAIL_CLIENT_SECRET=your_gmail_client_secret_here
GMAIL_TOKEN_PATH=token.json

# AI Configuration
MODAL_API_URL=your_modal_deployment_url_here
```

### Step 3: Run the Application

**Option 1: All-in-One (Recommended)**
```bash
# This automatically starts both MCP server and frontend
python project/enhanced.py
```
Open http://localhost:7861 in your browser

**Option 2: Run Separately**

Terminal 1 - Start the MCP server:
```bash
python project/gmail_mcp_server.py
```

Terminal 2 - Start the frontend:
```bash
python project/enhanced.py
```

## 🔧 Detailed Setup

### 1. Gmail API Setup
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a project or select existing one
3. Enable the Gmail API
4. Create OAuth 2.0 credentials (Desktop application)
5. Download as `credentials.json` into project directory

### 2. Modal Setup for Qwen AI
1. Sign up for a [Modal](https://modal.com/) account
2. Deploy the LLM service using the provided `llm.py` file:
   ```bash
   modal deploy project/llm.py
   ```
3. Copy the deployment URL to your `.env` file as `MODAL_API_URL`

### 3. First Run Authentication
When running the app for the first time:
1. The app will open a browser window for Gmail authentication
2. Allow the requested permissions
3. The app will create a `token.json` file for future sessions

## 📚 User Guide

### 💬 AI Chat Examples
Try these in the AI Assistant tab:
- "Show me my unread emails" 
- "Summarize emails from this week"
- "Find emails with attachments"
- "What are the main topics in my inbox?"
- "Any important emails I missed?"

### 🔍 Gmail Search Syntax
Use these in the Email Management tab:
- `is:unread` - Unread emails
- `from:sender@example.com` - From specific sender
- `subject:meeting` - Subject contains "meeting"
- `has:attachment` - Has attachments
- `newer_than:7d` - Newer than 7 days
- `older_than:1m` - Older than 1 month

### 📊 Email Triage
The Email Triage feature provides AI-powered analysis:
- Automatic categorization of emails
- Priority scoring for each email
- Action recommendations
- Visual representation of email importance
- Workflow suggestions based on email content

## 🛠️ MCP Tools Reference

### Available Tools

#### `fetch_emails`
Fetch emails with optional search query.

**Parameters:**
- `query` (string, optional): Gmail search query
- `max_results` (integer): Maximum number of emails (1-50)

#### `summarize_emails`
Generate email summary with statistics.

**Parameters:**
- `days` (integer): Number of days to analyze (1-30)
- `include_body` (boolean): Include email body previews

#### `search_emails`
Advanced email search with multiple filters.

**Parameters:**
- `from_address` (string): Filter by sender
- `subject_contains` (string): Filter by subject keywords
- `has_attachment` (boolean): Filter emails with attachments
- `is_unread` (boolean): Filter unread emails only
- `max_results` (integer): Maximum results

### Available Resources
- `gmail://inbox` - Access to Gmail inbox messages
- `gmail://unread` - Access to unread Gmail messages
- `gmail://recent` - Access to recent Gmail messages

## 🔎 Troubleshooting

### Common Issues

**"MCP Connection Failed"**
- Check if MCP server is running
- Verify network connectivity
- Ensure proper file paths

**"Gmail Authentication Failed"**
- Check that `credentials.json` exists and is valid
- Try removing `token.json` and re-authenticating
- Verify your Gmail account has API access enabled

**"Modal API Error"**
- Verify Modal deployment URL is correct in `.env` file
- Check for API rate limits or quotas
- Ensure connectivity to Modal's API servers

**"Import Errors"**
- Install all dependencies: `pip install -r requirements.txt`
- Check for compatible Python version (3.8+)
- Verify all required packages are installed

## 📋 Project Information

### Technology Stack
- **Frontend:** Gradio (Modern UI Framework)
- **AI:** Qwen 3-4B (hosted on Modal)
- **Email API:** Gmail API
- **Protocol:** Model Context Protocol (MCP)
- **Language:** Python 3.8+

### Why MCP Matters
The Model Context Protocol (MCP) integration provides:
- Standardized tool calling for AI assistants
- Clean separation between client and server
- Reusable components across applications
- Future compatibility with other MCP clients

### Security Features
- OAuth 2.0 for secure Gmail access
- No password storage
- Token-based authentication
- Local credential storage

## 🔗 Additional Resources
- [MCP Documentation](https://github.com/modelcontextprotocol/mcp)
- [Modal Documentation](https://modal.com/docs)
- [Gmail API Reference](https://developers.google.com/gmail/api/reference/rest)
- [Gradio Documentation](https://www.gradio.app/docs)

## 🙏 Acknowledgements
- Model Context Protocol (MCP) for the protocol specification
- Modal for AI model hosting
- Google for Gmail API
- Gradio for the user interface framework

## 📄 License
This project is licensed under the MIT License.