Gmail
Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Use when user asks to: search email, read email, send email, create email draft, mark as read, archive email, star email, or manage Gmail labels. Lightweight alternative to full Google Workspace MCP server with standalone OAuth authentication.From its SKILL.md
npx -y skills add sanjay3290/ai-skills --skill gmailAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- runs commandsInstructs the agent to run 8 commands, including `python scripts/auth.py login` and 7 more.
What its file declares
Copied from the file, not written here
The file declares its own license as Apache-2.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
4.8 KB, ~1.2k tokens by cl100k_base, as published. Nobody here has run it
Gmail
Lightweight Gmail integration with standalone OAuth authentication. No MCP server required.
⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.
First-Time Setup
Authenticate with Google (opens browser):
python scripts/auth.py login
Check authentication status:
python scripts/auth.py status
Logout when needed:
python scripts/auth.py logout
Commands
All operations via scripts/gmail.py. Auto-authenticates on first use if not logged in.
Search Emails
# Search with Gmail query syntax
python scripts/gmail.py search "from:[email protected] is:unread"
# Search recent emails (no query returns all)
python scripts/gmail.py search --limit 20
# Filter by label
python scripts/gmail.py search --label INBOX --limit 10
# Include spam and trash
python scripts/gmail.py search "subject:important" --include-spam-trash
Read Email Content
# Get full message content
python scripts/gmail.py get MESSAGE_ID
# Get just metadata (headers)
python scripts/gmail.py get MESSAGE_ID --format metadata
# Get minimal response (IDs only)
python scripts/gmail.py get MESSAGE_ID --format minimal
Send Emails
# Send a simple email
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message body"
# Send with CC and BCC
python scripts/gmail.py send --to "[email protected]" --cc "[email protected]" --bcc "[email protected]" \
--subject "Team Update" --body "Update message"
# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "[email protected]" --subject "Hello" --body "Message" \
--from "Mile9 Accounts <[email protected]>"
# Send HTML email
python scripts/gmail.py send --to "[email protected]" --subject "HTML Email" \
--body "<h1>Hello</h1><p>HTML content</p>" --html
Draft Management
# Create a draft
python scripts/gmail.py create-draft --to "[email protected]" --subject "Draft Subject" \
--body "Draft content"
# Send an existing draft
python scripts/gmail.py send-draft DRAFT_ID
Modify Messages (Labels)
# Mark as read (remove UNREAD label)
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD
# Mark as unread
python scripts/gmail.py modify MESSAGE_ID --add-label UNREAD
# Archive (remove from INBOX)
python scripts/gmail.py modify MESSAGE_ID --remove-label INBOX
# Star a message
python scripts/gmail.py modify MESSAGE_ID --add-label STARRED
# Unstar a message
python scripts/gmail.py modify MESSAGE_ID --remove-label STARRED
# Mark as important
python scripts/gmail.py modify MESSAGE_ID --add-label IMPORTANT
# Multiple label changes at once
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED
List Labels
# List all Gmail labels (system and user-created)
python scripts/gmail.py list-labels
Gmail Query Syntax
Gmail supports powerful search operators:
| Query | Description |
|---|---|
from:[email protected] | Emails from a specific sender |
to:[email protected] | Emails to a specific recipient |
subject:meeting | Emails with "meeting" in subject |
is:unread | Unread emails |
is:starred | Starred emails |
is:important | Important emails |
has:attachment | Emails with attachments |
after:2024/01/01 | Emails after a date |
before:2024/12/31 | Emails before a date |
newer_than:7d | Emails from last 7 days |
older_than:1m | Emails older than 1 month |
label:work | Emails with a specific label |
in:inbox | Emails in inbox |
in:sent | Sent emails |
in:trash | Trashed emails |
Combine with AND (space), OR, or - (NOT):
python scripts/gmail.py search "from:[email protected] is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:[email protected] -is:starred"
Common Label IDs
| Label | ID |
|---|---|
| Inbox | INBOX |
| Sent | SENT |
| Drafts | DRAFT |
| Spam | SPAM |
| Trash | TRASH |
| Starred | STARRED |
| Important | IMPORTANT |
| Unread | UNREAD |
Token Management
Tokens stored securely using the system keyring:
- macOS: Keychain
- Windows: Windows Credential Locker
- Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)
Service name: gmail-skill-oauth
Tokens automatically refresh when expired using Google's cloud function.
What ships with it: 5 files
30.4 KB alongside SKILL.md, 2 of them executable
scripts/
- auth.pyruns12.1 KB
- gmail.pyruns14.0 KB
- requirements.txt16 B
- README.md4.4 KB
- requirements.txt16 B
Gives 0 of the 12 instructions most mcp tooling skills give in ~1.2k tokens
Counted across 780 of the 1,136 authors here whose files we hold, read 2026-09-06
- Use Zod for input validationin 34 of 780, across 21 files
- Use stdio for local clientsin 27 of 780, across 10 files
- Restart Claude Code after configurationin 26 of 780, across 23 files
- Verify MCP server connection before using toolsin 23 of 780, across 17 files
- Define input schemas for every toolin 20 of 780, across 11 files
- Use Streamable HTTP for remote clientsin 18 of 780, across 8 files
- Pin SDK version in package.jsonin 17 of 780, across 6 files
- Keep server logic independent of transportin 16 of 780, across 6 files
- Verify SDK methods against official documentationin 15 of 780, across 5 files
- Format evaluation results as an XML filein 15 of 780, across 12 files
- Test servers using the MCP Inspectorin 15 of 780, across 14 files
- Create ten complex and independent evaluation questionsin 14 of 780, across 11 files
Said here and by no other author read
- Authenticate with Google using the login script
- Use the gmail script for all operations
- Search emails using Gmail query syntax
- Get message content by message ID
- Send emails with specified recipients and body
- Create drafts using the create-draft command
Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.