Gmail

A standalone Gmail client that handles search, read, send, and label management through command-line scripts with OAuth authentication. Ships with auth.py for login management and gmail.py for operations. Requires a Google Workspace account, not personal Gmail. Token storage uses system keyrings (macOS Keychain, Windows Credential Locker, Linux Secret Service), and tokens auto-refresh through Google's cloud function. Supports Gmail's full query syntax for searches, HTML emails, draft management, and all the usual label operations like starring and archiving. The lightweight approach means no MCP server to configure, just authenticate once and run Python commands directly.

skills.sh installs: 525
GitHub stars: 454
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add sanjay3290/ai-skills --skill gmail --agent claude-code

Installs into .claude/skills of the current project.

Files

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

SKILL.md on GitHub