Claude Skill

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 Goo

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download sanjay3290-ai-skills-skills_gmail-c842558.zip · 11 KB

Install

skills CLI npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/gmail
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
Git git clone https://github.com/sanjay3290/ai-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sanjay3290/ai-skills collection as a plugin from our marketplace. Git is the plain clone.

README

Gmail Skill

An AI agent skill for interacting with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the Agent Skills Standard.

Features

  • Search - Find emails using Gmail query syntax
  • Read - Get full message content
  • Send - Send plain text or HTML emails
  • Drafts - Create and send draft emails
  • Labels - Archive, star, mark read/unread

Lightweight alternative to the full Google Workspace MCP server.

⚠️ Requires Google Workspace account. Personal Gmail accounts are not supported.

Quick Start

1. Install dependencies

pip install keyring

2. Authenticate

python scripts/auth.py login

This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.

3. Test connection

python scripts/auth.py status

Usage Examples

Search Emails

# Search with Gmail query syntax
python scripts/gmail.py search "from:someone@example.com is:unread"

# Get recent emails
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 Emails

# Get full message content
python scripts/gmail.py get MESSAGE_ID

# Get just metadata (headers)
python scripts/gmail.py get MESSAGE_ID --format metadata

Send Emails

# Send a simple email
python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message body"

# Send with CC and BCC
python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
  --subject "Team Update" --body "Update message"

# Send HTML email
python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
  --body "<h1>Hello</h1><p>HTML content</p>" --html

Draft Management

# Create a draft
python scripts/gmail.py create-draft --to "user@example.com" --subject "Draft Subject" \
  --body "Draft content"

# Send an existing draft
python scripts/gmail.py send-draft DRAFT_ID

Modify Messages (Labels)

# Mark as read
python scripts/gmail.py modify MESSAGE_ID --remove-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

# Multiple changes
python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED

Command Reference

Command Description Arguments
search [query] Search emails query, --limit, --label
get <id> Read message message ID, --format
send Send email --to, --subject, --body, --html
create-draft Create draft --to, --subject, --body
send-draft <id> Send draft draft ID
modify <id> Change labels --add-label, --remove-label
list-labels List all labels -

Gmail Query Syntax

Query Description
from:user@example.com From specific sender
to:user@example.com To specific recipient
subject:meeting Subject contains "meeting"
is:unread Unread emails
is:starred Starred emails
has:attachment Has attachments
after:2024/01/01 After date
newer_than:7d Last 7 days
label:work Specific label

Combine with AND (space), OR, or - (NOT).

Common Labels

Label Description
INBOX Inbox
SENT Sent mail
STARRED Starred
IMPORTANT Important
UNREAD Unread
TRASH Trash
SPAM Spam

Token Management

Tokens stored securely using the system keyring:

  • macOS: Keychain
  • Windows: Windows Credential Locker
  • Linux: Secret Service API (GNOME Keyring, KDE Wallet)

Service name: gmail-skill-oauth

Troubleshooting

"Failed to get access token"

Run python scripts/auth.py login to authenticate.

"Message not found"

Check the message ID. Use search to find valid IDs.

"Permission denied"

Ensure you have the required Gmail permissions. Re-authenticate if needed.

License

Apache 2.0

Skill manifest

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:someone@example.com 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 "user@example.com" --subject "Hello" --body "Message body"

# Send with CC and BCC
python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
  --subject "Team Update" --body "Update message"

# Send from an alias (must be configured in Gmail settings)
python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message" \
  --from "Mile9 Accounts <accounts@mile9.io>"

# Send HTML email
python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
  --body "<h1>Hello</h1><p>HTML content</p>" --html

Draft Management

# Create a draft
python scripts/gmail.py create-draft --to "user@example.com" --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:user@example.com Emails from a specific sender
to:user@example.com 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:boss@company.com is:unread newer_than:1d"
python scripts/gmail.py search "subject:urgent OR subject:important"
python scripts/gmail.py search "from:newsletter@example.com -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.

Files (ai-skills)
  • scripts
    • auth.py 12.1 KB
      Loading…
    • gmail.py 14 KB
      Loading…
    • requirements.txt 16 B
      Loading…
  • README.md 4.4 KB
    # Gmail Skill
    
    An AI agent skill for interacting with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the [Agent Skills Standard](https://agentskills.io).
    
    ## Features
    
    - **Search** - Find emails using Gmail query syntax
    - **Read** - Get full message content
    - **Send** - Send plain text or HTML emails
    - **Drafts** - Create and send draft emails
    - **Labels** - Archive, star, mark read/unread
    
    Lightweight alternative to the full [Google Workspace MCP server](https://github.com/gemini-cli-extensions/workspace).
    
    > **⚠️ Requires Google Workspace account.** Personal Gmail accounts are not supported.
    
    ## Quick Start
    
    ### 1. Install dependencies
    
    ```bash
    pip install keyring
    ```
    
    ### 2. Authenticate
    
    ```bash
    python scripts/auth.py login
    ```
    
    This opens a browser for Google OAuth. Tokens are stored securely in your system keyring.
    
    ### 3. Test connection
    
    ```bash
    python scripts/auth.py status
    ```
    
    ## Usage Examples
    
    ### Search Emails
    
    ```bash
    # Search with Gmail query syntax
    python scripts/gmail.py search "from:someone@example.com is:unread"
    
    # Get recent emails
    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 Emails
    
    ```bash
    # Get full message content
    python scripts/gmail.py get MESSAGE_ID
    
    # Get just metadata (headers)
    python scripts/gmail.py get MESSAGE_ID --format metadata
    ```
    
    ### Send Emails
    
    ```bash
    # Send a simple email
    python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message body"
    
    # Send with CC and BCC
    python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
      --subject "Team Update" --body "Update message"
    
    # Send HTML email
    python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
      --body "<h1>Hello</h1><p>HTML content</p>" --html
    ```
    
    ### Draft Management
    
    ```bash
    # Create a draft
    python scripts/gmail.py create-draft --to "user@example.com" --subject "Draft Subject" \
      --body "Draft content"
    
    # Send an existing draft
    python scripts/gmail.py send-draft DRAFT_ID
    ```
    
    ### Modify Messages (Labels)
    
    ```bash
    # Mark as read
    python scripts/gmail.py modify MESSAGE_ID --remove-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
    
    # Multiple changes
    python scripts/gmail.py modify MESSAGE_ID --remove-label UNREAD --add-label STARRED
    ```
    
    ## Command Reference
    
    | Command | Description | Arguments |
    |---------|-------------|-----------|
    | `search [query]` | Search emails | query, `--limit`, `--label` |
    | `get <id>` | Read message | message ID, `--format` |
    | `send` | Send email | `--to`, `--subject`, `--body`, `--html` |
    | `create-draft` | Create draft | `--to`, `--subject`, `--body` |
    | `send-draft <id>` | Send draft | draft ID |
    | `modify <id>` | Change labels | `--add-label`, `--remove-label` |
    | `list-labels` | List all labels | - |
    
    ## Gmail Query Syntax
    
    | Query | Description |
    |-------|-------------|
    | `from:user@example.com` | From specific sender |
    | `to:user@example.com` | To specific recipient |
    | `subject:meeting` | Subject contains "meeting" |
    | `is:unread` | Unread emails |
    | `is:starred` | Starred emails |
    | `has:attachment` | Has attachments |
    | `after:2024/01/01` | After date |
    | `newer_than:7d` | Last 7 days |
    | `label:work` | Specific label |
    
    Combine with AND (space), OR, or `-` (NOT).
    
    ## Common Labels
    
    | Label | Description |
    |-------|-------------|
    | `INBOX` | Inbox |
    | `SENT` | Sent mail |
    | `STARRED` | Starred |
    | `IMPORTANT` | Important |
    | `UNREAD` | Unread |
    | `TRASH` | Trash |
    | `SPAM` | Spam |
    
    ## Token Management
    
    Tokens stored securely using the system keyring:
    - **macOS**: Keychain
    - **Windows**: Windows Credential Locker
    - **Linux**: Secret Service API (GNOME Keyring, KDE Wallet)
    
    Service name: `gmail-skill-oauth`
    
    ## Troubleshooting
    
    ### "Failed to get access token"
    Run `python scripts/auth.py login` to authenticate.
    
    ### "Message not found"
    Check the message ID. Use `search` to find valid IDs.
    
    ### "Permission denied"
    Ensure you have the required Gmail permissions. Re-authenticate if needed.
    
    ## License
    
    Apache 2.0
    
  • requirements.txt 16 B
    Loading…
  • SKILL.md 4.8 KB
    ---
    name: gmail
    description: |
      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.
    license: Apache-2.0
    metadata:
      author: sanjay3290
      version: "1.0"
    ---
    
    # 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):
    ```bash
    python scripts/auth.py login
    ```
    
    Check authentication status:
    ```bash
    python scripts/auth.py status
    ```
    
    Logout when needed:
    ```bash
    python scripts/auth.py logout
    ```
    
    ## Commands
    
    All operations via `scripts/gmail.py`. Auto-authenticates on first use if not logged in.
    
    ### Search Emails
    
    ```bash
    # Search with Gmail query syntax
    python scripts/gmail.py search "from:someone@example.com 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
    
    ```bash
    # 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
    
    ```bash
    # Send a simple email
    python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message body"
    
    # Send with CC and BCC
    python scripts/gmail.py send --to "user@example.com" --cc "cc@example.com" --bcc "bcc@example.com" \
      --subject "Team Update" --body "Update message"
    
    # Send from an alias (must be configured in Gmail settings)
    python scripts/gmail.py send --to "user@example.com" --subject "Hello" --body "Message" \
      --from "Mile9 Accounts <accounts@mile9.io>"
    
    # Send HTML email
    python scripts/gmail.py send --to "user@example.com" --subject "HTML Email" \
      --body "<h1>Hello</h1><p>HTML content</p>" --html
    ```
    
    ### Draft Management
    
    ```bash
    # Create a draft
    python scripts/gmail.py create-draft --to "user@example.com" --subject "Draft Subject" \
      --body "Draft content"
    
    # Send an existing draft
    python scripts/gmail.py send-draft DRAFT_ID
    ```
    
    ### Modify Messages (Labels)
    
    ```bash
    # 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
    
    ```bash
    # 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:user@example.com` | Emails from a specific sender |
    | `to:user@example.com` | 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):
    ```bash
    python scripts/gmail.py search "from:boss@company.com is:unread newer_than:1d"
    python scripts/gmail.py search "subject:urgent OR subject:important"
    python scripts/gmail.py search "from:newsletter@example.com -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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.