agentic_implementation/README_MCP.md

# Email Assistant MCP Server

This is a Gradio-based MCP (Model Context Protocol) server that allows Claude Desktop to interact with your Gmail emails.

## Features

- **Email Search**: Search your emails using natural language queries
- **Email Details**: Get full details of specific emails by message ID
- **Pattern Analysis**: Analyze email patterns from specific senders over time

## Setup

1. **Install Dependencies**:
   ```bash
   pip install -r requirements_mcp.txt
   ```

2. **Set up Gmail App Password**:
   - Enable 2-Factor Authentication on your Gmail account
   - Generate an App Password: https://support.google.com/accounts/answer/185833
   - Keep your Gmail address and app password ready

3. **Run the MCP Server**:
   ```bash
   python email_mcp_server.py
   ```

   The server will start and show you the MCP endpoint URL, typically:
   ```
   http://localhost:7860/gradio_api/mcp/sse
   ```

## Claude Desktop Configuration

Add this configuration to your Claude Desktop MCP settings:

**For SSE-supported clients:**
```json
{
  "mcpServers": {
    "email-assistant": {
      "url": "http://localhost:7860/gradio_api/mcp/sse"
    }
  }
}
```

**For Claude Desktop (requires mcp-remote):**
```json
{
  "mcpServers": {
    "email-assistant": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:7860/gradio_api/mcp/sse"
      ]
    }
  }
}
```

## Available Tools

### 1. search_emails
Search your emails using natural language queries.

**Parameters:**
- `email_address`: Your Gmail address
- `app_password`: Your Gmail app password
- `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? My email is john@gmail.com and my app password is xxxx-xxxx-xxxx-xxxx"

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

**Parameters:**
- `email_address`: Your Gmail address
- `app_password`: Your Gmail app password
- `message_id`: Message ID from search results

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

**Parameters:**
- `email_address`: Your Gmail address
- `app_password`: Your Gmail app password
- `sender_keyword`: Sender to analyze (e.g., "amazon", "google")
- `days_back`: Number of days to analyze (default: "30")

## Security Notes

- Your email credentials are only used for the duration of each tool call
- Credentials are not stored or logged by the server
- All communication happens locally on your machine
- The server only exposes the MCP interface, not a public web interface

## Troubleshooting

1. **Connection Issues**: Make sure your Gmail app password is correct and 2FA is enabled
2. **MCP Client Issues**: Try restarting Claude Desktop after configuration changes
3. **Search Issues**: The tool searches in FROM, SUBJECT, and BODY fields for keywords

## Example Queries

Once configured with Claude Desktop, you can ask:

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

Claude will automatically call the appropriate tools with your provided credentials.