# Gmail Integration for Personal Assistant

**Date:** 2025-12-29
**Status:** Approved

## Overview

Integrate Gmail read access into the Personal Assistant agent via MCP server, enabling email search, unread checking, and urgency detection.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Personal Assistant                    │
│                        (Opus)                           │
└─────────────────────────┬───────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               ▼               ▼
   ┌──────────┐    ┌──────────┐    ┌──────────┐
   │  Gmail   │    │  Other   │    │  Master  │
   │  Skill   │    │  Skills  │    │  Orch    │
   └────┬─────┘    └──────────┘    └──────────┘
        │
        ▼
┌───────────────┐
│  Gmail MCP    │  ← theposch/gmail-mcp (Python)
│    Server     │  ← OAuth: gmail.readonly scope
└───────┬───────┘
        │
        ▼
   Gmail API
```

## Key Decisions

| Aspect | Decision | Rationale |
|--------|----------|-----------|
| Access level | Read-only | Start minimal, upgrade later if needed |
| Integration | MCP Server | Native Claude Code mechanism |
| Server | theposch/gmail-mcp | Python-based, well-documented, maintained |
| OAuth scope | gmail.readonly | Enforce read-only at OAuth level |
| Config location | ~/.claude/mcp/ | Dedicated directory for MCP servers |
| Tool access | Raw tools + skill | Flexibility + common patterns |
| Urgency detection | Content-based | Keywords in subject/body, no VIP list needed |

## Directory Structure

```
~/.claude/
├── mcp/
│   ├── servers.json              # MCP server registry
│   └── gmail/
│       ├── config.json           # Gmail-specific config
│       └── venv/                 # Python virtualenv
├── skills/
│   └── gmail/
│       └── SKILL.md              # Gmail skill definition
│
~/.gmail-mcp/
    ├── credentials.json          # Google OAuth client (user provides)
    └── token.json                # Refresh token (auto-managed)
```

## MCP Server Configuration

**servers.json:**

```json
{
  "gmail": {
    "command": "~/.claude/mcp/gmail/venv/bin/python",
    "args": ["-m", "gmail_mcp"],
    "env": {
      "GMAIL_CREDENTIALS_PATH": "~/.gmail-mcp/credentials.json",
      "GMAIL_TOKEN_PATH": "~/.gmail-mcp/token.json"
    }
  }
}
```

## Gmail Skill

**Location:** `~/.claude/skills/gmail/SKILL.md`

### Patterns

| Pattern | Description |
|---------|-------------|
| check-unread | Count and summarize unread emails (limit 20, group by sender/thread) |
| check-urgent | Find emails with urgency signals in content |
| search \<query\> | Translate natural language to Gmail query syntax |

### Urgency Detection

Content-based signals:
- **Subject keywords:** urgent, asap, action required, immediate, deadline, time-sensitive, critical, important
- **Body phrases:** "by end of day", "by EOD", "as soon as possible", "please respond", "awaiting your reply"

### Policy

Read-only enforced at OAuth scope level. No send, delete, or modify operations available.

## Implementation Plan

| Phase | Owner | Description |
|-------|-------|-------------|
| 1. Google Cloud Setup | User | Create project, enable Gmail API, create OAuth credentials, download credentials.json |
| 2. MCP Server Installation | PA/Agent | Create directories, set up Python venv, install gmail-mcp |
| 3. OAuth Flow | User | Run auth command, complete browser consent |
| 4. Claude Code Integration | PA/Agent | Configure MCP in settings, verify tools appear |
| 5. Skill Creation | PA/Agent | Create Gmail skill with patterns |
| 6. PA Integration | PA/Agent | Update PA docs, test end-to-end |

## Security Model

- Read-only enforced at OAuth level (not just policy)
- Tokens stored locally in ~/.gmail-mcp/, never transmitted
- Can revoke access anytime via Google account settings
- MCP server runs locally, emails never pass through third parties

## Upgrade Path

To add write capabilities later:

1. Re-run OAuth flow with `gmail.modify` scope
2. Add send/manage patterns to Gmail skill
3. Update skill policy documentation
4. No server changes needed

## Sources

- [theposch/gmail-mcp](https://github.com/theposch/gmail-mcp) - MCP server implementation
- [GongRzhe/Gmail-MCP-Server](https://github.com/GongRzhe/Gmail-MCP-Server) - Alternative implementation