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

pip install -r requirements_oauth.txt

Step 2: Run the Interactive Setup

The setup script will guide you through the entire process:

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

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:

{
  "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:

python setup_oauth.py --status

Re-authenticate:

python setup_oauth.py --auth

Clear stored credentials:

python setup_oauth.py --clear

Show help:

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:

python setup_oauth.py

"Not authenticated" error:

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:

pip install -r requirements_oauth.txt

"Permission denied" on credential files:

# 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