will/claude-code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
claude-code/docs/plans/2025-12-29-gmail-integration-design.md
OpenCode Test 51726d96a0 Add Gmail integration design for PA agent 
Design for read-only Gmail access via MCP server, including:
- Architecture using theposch/gmail-mcp
- Gmail skill with search, check-unread, check-urgent patterns
- Content-based urgency detection
- Implementation phases with user/agent ownership

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-29 13:43:42 -08:00

5.0 KiB
Raw Permalink Blame History

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