gmail

Gmail MCP — Usage Guide

This skill covers how to use the bundled Gmail MCP server correctly.

Search query syntax

Gmail's query language is the most powerful way to filter. Prefer it over listing + client-side filtering.

Intent	Query
Unread in inbox	in:inbox is:unread
From a person	from:alice@x.com
With attachments	has:attachment
Large messages	larger:5M
Time window	newer_than:7d, older_than:1y, after:2026/01/01
Specific label	label:work
Category	category:promotions (also: updates, social, forums)
Thread with X	from:alice OR to:alice
Exact phrase	"launch plan"
Exclude	-from:noreply@

System labels (always available)

INBOX, SENT, DRAFT, TRASH, SPAM, UNREAD, STARRED, IMPORTANT, CATEGORY_PERSONAL, CATEGORY_PROMOTIONS, CATEGORY_SOCIAL, CATEGORY_UPDATES, CATEGORY_FORUMS.

Common label recipes:

• Archive: remove INBOX.
• Mark read: remove UNREAD.
• Mark unread: add UNREAD.
• Star: add STARRED.
• Move to trash: use gmail_trash (don't add TRASH manually).

Safe send discipline

• Always draft first, then send for anything non-trivial. Call gmail_create_draft, show the draft, then gmail_send_draft after user confirmation.
• For replies, use gmail_reply — it handles In-Reply-To, References, and threadId for correct threading.
• For forwards, use gmail_forward — it builds the proper "Forwarded message" quote.
• Never call gmail_send / gmail_reply / gmail_forward without the user seeing the final content first.

Attachments

• Inbound: gmail_get_attachment returns base64 content inline for files ≤ 1 MB; otherwise metadata only. Save to the user's workspace with a descriptive filename.
• Outbound: pass an attachments array with { filename, mimeType, dataBase64 }. Use standard base64, NOT base64url. Keep each attachment under ~10 MB to stay well inside Worker limits.

Unsubscribe flow

1. gmail_inspect_unsubscribe to see what's available.
2. gmail_unsubscribe to act on it — it will:
   • Do RFC 8058 one-click (HTTPS POST with List-Unsubscribe=One-Click) when supported.
   • Otherwise send the mailto: command the sender requested.
   • If neither is available, return the URL and let the user finish manually.
3. Optionally follow up by batch-archiving existing messages from the same sender.

Bulk operations

• Prefer gmail_batch_modify_labels (up to 1000 ids per call) over looping gmail_modify_labels.
• When archiving many newsletters, group by sender first and confirm counts with the user before executing.

Pagination

All list tools accept pageToken. When the user asks for "all" of something, either page until exhaustion (be careful — quota is 250 units/user/second) or offer to process the first page and continue on request.

What to avoid

• Don't use gmail_delete unless the user explicitly says "permanently delete". gmail_trash is the safe default.
• Don't modify or trash messages that are personally addressed (2 or fewer To recipients, From a real person) without confirmation.
• Don't ever respond to a suspected phishing message from within the tools — flag it to the user.