Skip to content

CLAUDE.md

Latest commit

 

History

History
180 lines (145 loc) · 7.55 KB

CLAUDE.md

File metadata and controls

180 lines (145 loc) · 7.55 KB
Raw

Gmail MCP Guidelines for Claude

Guidelines for using the Gmail MCP server with Claude.

Available Operations

19 operations available for comprehensive Gmail management.

Email Operations (10)

  • send_email - Send emails with optional attachments (plain text, HTML, or multipart)
  • draft_email - Create email drafts with attachments support
  • read_email - Read email content with full MIME parsing and attachment information
  • search_emails - Search emails using Gmail query syntax
  • count_emails - Get exact email count for a label using Gmail API label metadata (provides total and unread counts)
  • modify_email - Modify email labels (add/remove labels)
  • delete_email - Permanently delete emails
  • download_attachment - Download email attachments to local filesystem
  • batch_modify_emails - Modify labels for multiple emails in batches
  • batch_delete_emails - Delete multiple emails in batches

Label Management (5)

  • list_email_labels - List all Gmail labels (system and user)
  • create_label - Create a new Gmail label with visibility settings
  • update_label - Update label properties (name, visibility)
  • delete_label - Delete a user-created label
  • get_or_create_label - Get existing label by name or create if it doesn't exist

Filter Management (5)

  • create_filter - Create a custom Gmail filter with criteria and actions
  • list_filters - List all Gmail filters
  • get_filter - Get details of a specific filter
  • delete_filter - Delete a Gmail filter
  • create_filter_from_template - Create a filter using pre-built templates

Usage Guidelines

Before Operations

  1. Verify authentication status - if authentication fails, guide user to run npm run auth
  2. For email operations, check if message IDs are valid
  3. For label operations, check if labels exist before creating duplicates
  4. For filter operations, understand the user's filtering needs

Email Operations

Sending Emails

  • Use send_email for immediate sending
  • Use draft_email to create drafts for review
  • Support attachments by providing file paths in the attachments array
  • Support HTML emails with htmlBody parameter
  • Support multipart emails (both plain text and HTML) with mimeType: "multipart/alternative"

Reading Emails

  • read_email returns full email content including:
    • Headers (subject, from, to, date)
    • Plain text and HTML content
    • Attachment information (filename, type, size, download ID)
    • Thread ID for conversation context

Searching Emails

  • Use Gmail search syntax: from:example@gmail.com, subject:meeting, has:attachment, etc.
  • Combine operators: from:boss@company.com after:2024/01/01 has:attachment
  • Limit results with maxResults parameter (default: 10, max: 500)

Counting Emails

  • Use count_emails to get exact counts from label metadata (no pagination needed)
  • Provides both total and unread message counts
  • Use labelId or labelName parameter (e.g., "INBOX", "UNREAD", "STARRED", "SENT", or user label names)
  • Common system labels: INBOX, UNREAD, STARRED, SENT, DRAFT, TRASH, SPAM
  • Use list_email_labels first to see all available labels and their IDs

Modifying Emails

  • Use modify_email to add/remove labels
  • Common labels: INBOX, UNREAD, IMPORTANT, STARRED, TRASH
  • Use batch_modify_emails for bulk operations (up to 50 per batch)

Label Management

Creating Labels

  • Use descriptive names: Work - Urgent not label1
  • Set visibility options:
    • messageListVisibility: show or hide
    • labelListVisibility: labelShow, labelShowIfUnread, or labelHide
  • Use get_or_create_label to avoid duplicates

Organizing with Labels

  • List all labels first to see existing structure
  • Create labels before applying them to emails
  • System labels cannot be deleted or modified

Filter Management

Creating Filters

  • Define criteria: from, to, subject, query, hasAttachment, size, etc.
  • Define actions: addLabelIds, removeLabelIds, forward
  • Use templates for common scenarios:
    • fromSender - Filter emails from specific sender
    • withSubject - Filter by subject text
    • withAttachments - Filter emails with attachments
    • largeEmails - Filter emails larger than specified size
    • containingText - Filter emails containing specific text
    • mailingList - Filter mailing list emails

Filter Templates

  • fromSender: Archive emails from specific sender
  • withSubject: Mark emails with specific subject as read
  • withAttachments: Label all emails with attachments
  • largeEmails: Label large emails for review
  • containingText: Mark important emails containing specific keywords
  • mailingList: Archive mailing list emails

Attachment Handling

Sending Attachments

  • Provide file paths in attachments array
  • Files are automatically detected and attached
  • Gmail has 25MB limit per email
  • All common file types supported (PDF, DOCX, images, etc.)

Downloading Attachments

  • First read email to get attachment IDs
  • Use download_attachment with message ID and attachment ID
  • Optionally specify savePath and filename
  • Original filename used if not specified

Common Workflows

Organizing Inbox

  1. List all labels to see current structure
  2. Create new labels as needed
  3. Search for emails to organize
  4. Use batch_modify_emails to apply labels in bulk
  5. Create filters to auto-organize future emails

Email Cleanup

  1. Search for emails to delete (e.g., from:newsletter@company.com older_than:1y)
  2. Use batch_delete_emails for bulk deletion
  3. Create filters to auto-archive or delete similar emails

Setting Up Filters

  1. Identify email patterns (sender, subject, content)
  2. Choose appropriate template or create custom filter
  3. Define labels to apply
  4. Test filter with existing emails
  5. Create filter to automate future emails

Managing Attachments

  1. Search for emails with attachments: has:attachment
  2. Read email to see attachment details
  3. Download important attachments
  4. Create filter to label emails with attachments

Error Handling

  • Authentication fails: Guide user to run npm run auth or place gcp-oauth.keys.json in correct location
  • Invalid message ID: Use search_emails to find correct message IDs
  • Label not found: Use list_email_labels to find correct label IDs
  • File not found: Verify attachment file paths are correct and accessible
  • API errors: Check Gmail API quotas and rate limits
  • Permission errors: Verify OAuth scopes include gmail.modify and gmail.settings.basic

Important Notes

  • Message IDs: Gmail message IDs are long alphanumeric strings
  • Label IDs: System labels use uppercase (e.g., INBOX, UNREAD), user labels use Label_ prefix
  • Batch operations: Process up to 50 emails per batch (configurable)
  • Attachments: 25MB limit per email, files processed locally
  • OAuth tokens: Auto-refresh when expired
  • Thread IDs: Use thread IDs to maintain conversation context
  • Search syntax: Use Gmail's powerful search operators for precise filtering

Best Practices

  1. Always verify before deleting: Use read_email to confirm before delete_email
  2. Use batch operations: More efficient for multiple emails
  3. Create filters proactively: Set up filters to prevent inbox clutter
  4. Organize with labels: Create a label hierarchy for better organization
  5. Test filters: Create filters and test with existing emails before relying on them
  6. Backup important emails: Download attachments before bulk operations
  7. Use search effectively: Combine search operators for precise results