# Gmail MCP Server

Model Context Protocol (MCP) server for Gmail API integration. Provides 17 tools for email management, labels, threads, attachments, and drafts.

## Features

### Email Operations (7 tools)
- **gmail_search_messages** - Search using Gmail query syntax (from:, to:, subject:, is:unread)
- **gmail_get_message** - Get full message content with headers and body
- **gmail_send_message** - Send email with to/cc/bcc recipients
- **gmail_delete_message** - Permanently delete message (bypass trash)
- **gmail_trash_message** - Move to trash (reversible)
- **gmail_untrash_message** - Restore from trash
- **gmail_modify_message_labels** - Add/remove labels from message

### Labels (3 tools)
- **gmail_list_labels** - List all labels with IDs and types
- **gmail_create_label** - Create new custom label
- **gmail_delete_label** - Remove custom label

### Threads (3 tools)
- **gmail_list_threads** - List conversation threads
- **gmail_get_thread** - Get full thread with all messages
- **gmail_modify_thread_labels** - Apply/remove labels from entire thread

### Attachments (1 tool)
- **gmail_get_attachment** - Download attachment data

### Drafts (3 tools)
- **gmail_list_drafts** - List draft messages
- **gmail_create_draft** - Create new draft
- **gmail_send_draft** - Send existing draft

## Installation

### 1. Install Dependencies

```bash
cd ~/repos/3-resources/MCP/mcp-proxy/gmail-mcp
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

### 2. Google Cloud Console Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select existing project
3. Enable the Gmail API:
   - Navigate to "APIs & Services" > "Library"
   - Search for "Gmail API"
   - Click "Enable"
4. Create OAuth 2.0 credentials:
   - Navigate to "APIs & Services" > "Credentials"
   - Click "Create Credentials" > "OAuth client ID"
   - Application type: "Desktop app"
   - Name: "Gmail MCP Server"
   - Click "Create"
5. Download credentials as `credentials.json`

### 3. Initial OAuth Flow

Run the initial OAuth flow to obtain a refresh token:

```bash
python3 oauth_setup.py
```

This will:
- Open a browser for Google OAuth consent
- Request gmail.modify scope
- Save refresh token to display

Copy the refresh token for the next step.

### 4. Store Credentials in OpenBao

Store the OAuth credentials in OpenBao:

```bash
# Ensure OpenBao agent is running
start-openbao-mcp

# Store credentials (replace values with your actual credentials)
bao kv put secret/client0/prod-mcp-gmail-$(git config user.email | cut -d'@' -f1) \
  client_id="YOUR_CLIENT_ID.apps.googleusercontent.com" \
  client_secret="YOUR_CLIENT_SECRET" \
  refresh_token="YOUR_REFRESH_TOKEN"
```

**Secret Path Pattern**: `secret/{client}/{env}-mcp-gmail-{username}`
- Example: `secret/client0/prod-mcp-gmail-samuel`
- Username is auto-detected from git config user.email

### 5. Test the Server

```bash
# Test server startup
python gmail_mcp.py
# Should print "MCP_SERVER_READY" to stderr

# Test with MCP Inspector (in separate terminal)
npx @modelcontextprotocol/inspector python gmail_mcp.py
```

### 6. Deploy to mcp-proxy

Add to `~/.claude/mcp-proxy/config.json`:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["/home/samuel/repos/3-resources/MCP/mcp-proxy/gmail-mcp/gmail_mcp.py"],
      "env": {}
    }
  }
}
```

Then run structure_generator to create hierarchy files:

```bash
cd ~/repos/3-resources/MCP/mcp-proxy
./structure_generator.py
```

## Development Mode

For local development without OpenBao:

```bash
export OPENBAO_DEV_MODE=1
export GMAIL_CLIENT_ID="your-client-id"
export GMAIL_CLIENT_SECRET="your-client-secret"
export GMAIL_REFRESH_TOKEN="your-refresh-token"

python gmail_mcp.py
```

## OAuth Scopes

This server requires the **gmail.modify** scope:
- `https://www.googleapis.com/auth/gmail.modify`

This provides full mailbox access including:
- Read messages and threads
- Send messages
- Modify labels
- Delete messages
- Manage drafts

## Security

- **Never commit credentials.json or tokens to git**
- OAuth refresh tokens are stored securely in OpenBao
- Access tokens are refreshed automatically on each request
- All API communication uses HTTPS

## Troubleshooting

### "OPENBAO_ERROR: Agent not running"

Start the OpenBao agent:
```bash
export BW_SESSION=$(bw unlock --raw)
start-openbao-mcp
```

### "Failed to refresh OAuth token"

The refresh token may be invalid or expired. Run `python oauth_setup.py` again to generate a new one.

### "Permission denied" errors

Ensure the OAuth consent screen includes the gmail.modify scope. You may need to re-authorize.

### Rate Limiting

Gmail API has these limits:
- 1 billion quota units per day
- 250 quota units per user per second
- Batch requests: 100 requests per batch

The server handles rate limit errors automatically with retry suggestions.

## Sources

**Gmail API Documentation:**
- [Gmail API Reference](https://developers.google.com/workspace/gmail/api/reference/rest)
- [Python Quickstart](https://developers.google.com/workspace/gmail/api/quickstart/python)
- [OAuth 2.0 for Google APIs](https://developers.google.com/identity/protocols/oauth2)

**MCP Documentation:**
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)