claude-code/docs/plans/2025-12-29-gmail-integration-design.md

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:

{
  "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 - MCP server implementation
• GongRzhe/Gmail-MCP-Server - Alternative implementation