agentic_implementation/README_OAuth.md

# Gmail MCP Server with OAuth Authentication

This is an enhanced version of the Gmail MCP (Model Context Protocol) server that uses **OAuth 2.0 authentication** instead of requiring users to provide email credentials for each query.

## 🚀 Key Features

- **OAuth 2.0 Authentication**: Secure authentication flow using Google's OAuth system
- **One-time Setup**: Authenticate once, use anywhere
- **Automatic Token Refresh**: Handles token expiration automatically
- **Encrypted Storage**: Credentials are encrypted and stored securely
- **No More Password Sharing**: No need to provide email/password to Claude

## 📋 Prerequisites

1. **Google Account**: You need a Gmail account
2. **Google Cloud Project**: Free to create
3. **Python 3.8+**: Required for running the server

## 🛠️ Setup Instructions

### Step 1: Install Dependencies

```bash
pip install -r requirements_oauth.txt
```

### Step 2: Run the Interactive Setup

The setup script will guide you through the entire process:

```bash
python setup_oauth.py
```

This will walk you through:
1. Creating a Google Cloud project
2. Enabling the Gmail API
3. Setting up OAuth consent screen
4. Creating OAuth credentials
5. Testing the authentication flow

### Step 3: Start the MCP Server

```bash
python email_mcp_server_oauth.py
```

The server will start and show you:
- Authentication status
- MCP endpoint URL
- Web interface URL

## 🔧 Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "gmail-oauth": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/sse"
      ]
    }
  }
}
```

## 🔍 Available Tools

### 1. search_emails
Search your emails using natural language queries - **no credentials needed!**

**Parameters:**
- `query`: Natural language query (e.g., "show me emails from amazon last week")

**Example Usage in Claude:**
> "Can you search my emails for messages from Swiggy in the last week?"

### 2. get_email_details
Get full details of a specific email by message ID.

**Parameters:**
- `message_id`: Message ID from search results

### 3. analyze_email_patterns
Analyze email patterns from a specific sender over time.

**Parameters:**
- `sender_keyword`: Sender to analyze (e.g., "amazon", "google")
- `days_back`: Number of days to analyze (default: "30")

### 4. authenticate_user
Trigger the OAuth authentication flow from Claude Desktop.

**Parameters:** None

### 5. get_authentication_status
Check current authentication status.

**Parameters:** None

## 🔐 Security Features

### Encrypted Storage
- All credentials are encrypted using Fernet encryption
- Encryption keys are stored securely with proper permissions
- No plaintext credentials are ever stored

### OAuth Benefits
- No need to share Gmail passwords
- Granular permission control
- Easy revocation from Google Account settings
- Automatic token refresh

### Local Storage
- All data stored locally on your machine
- No cloud storage of credentials
- You maintain full control

## 🔧 Advanced Usage

### Command Line Tools

Check authentication status:
```bash
python setup_oauth.py --status
```

Re-authenticate:
```bash
python setup_oauth.py --auth
```

Clear stored credentials:
```bash
python setup_oauth.py --clear
```

Show help:
```bash
python setup_oauth.py --help
```

### Web Interface

When the server is running, you can access the web interface at:
```
http://localhost:7860
```

Use this interface to:
- Check authentication status
- Trigger authentication flow
- Test email search functionality

## 🆚 Comparison: OAuth vs App Passwords

| Feature | App Password (Old) | OAuth (New) |
|---------|-------------------|-------------|
| **Setup Complexity** | Simple | One-time setup required |
| **Security** | Share app password | No password sharing |
| **User Experience** | Enter credentials each time | Authenticate once |
| **Revocation** | Change app password | Revoke from Google Account |
| **Token Management** | Manual | Automatic refresh |
| **Scope Control** | Full Gmail access | Granular permissions |

## 🐛 Troubleshooting

### Authentication Issues

**"OAuth not configured" error:**
```bash
python setup_oauth.py
```

**"Not authenticated" error:**
```bash
python setup_oauth.py --auth
```

**Authentication timeout:**
- Check if port 8080 is available
- Try disabling firewall temporarily
- Ensure browser can access localhost:8080

### Common Issues

**"No module named 'google.auth'" error:**
```bash
pip install -r requirements_oauth.txt
```

**"Permission denied" on credential files:**
```bash
# Check permissions
ls -la ~/.mailquery_oauth/
# Should show restricted permissions (600/700)
```

**Browser doesn't open:**
- Copy the authorization URL manually
- Paste it in your browser
- Complete the flow manually

### Getting Help

1. Check authentication status: `python setup_oauth.py --status`
2. Review server logs for detailed error messages
3. Ensure Google Cloud project is properly configured
4. Verify OAuth consent screen is set up correctly

## 📁 File Structure

```
~/.mailquery_oauth/
├── client_secret.json    # OAuth client configuration
├── token.pickle         # Encrypted access/refresh tokens
└── key.key             # Encryption key (secure permissions)
```

## 🔄 Migration from App Password Version

If you're migrating from the app password version:

1. Run the new OAuth setup: `python setup_oauth.py`
2. Update your Claude Desktop configuration to use the new server
3. The old environment variables (EMAIL_ID, APP_PASSWORD) are no longer needed

## 📞 Support

For issues or questions:
1. Check the troubleshooting section above
2. Review the setup script output for specific guidance
3. Ensure all prerequisites are met
4. Verify Google Cloud project configuration

## 🎯 Example Queries for Claude

Once set up, you can ask Claude:

- "Search my emails for messages from Amazon in the last month"
- "Show me emails from my bank from last week" 
- "Analyze my LinkedIn email patterns over the last 60 days"
- "Find emails from Swiggy today"
- "Get details of the email with ID xyz123"

Claude will automatically use the OAuth-authenticated tools without asking for credentials!

## 🔒 Privacy & Data

- **No data leaves your machine**: All processing happens locally
- **Google only provides**: Access to your Gmail via official APIs
- **We store**: Encrypted authentication tokens only
- **We never store**: Email content, passwords, or personal data
- **You control**: Access can be revoked anytime from Google Account settings