A Claude Agent Skill for Gmail operations via CLI. Read, draft, send, archive, label, and batch-process emails.
-
Create OAuth credentials at Google Cloud Console:
- Create project → Enable Gmail API
- Configure OAuth consent screen (External, add yourself as test user)
- Create OAuth Client ID (Desktop app)
-
Configure credentials:
cp credentials.example.json credentials.json # Edit credentials.json with your client_id and client_secret -
Install dependencies:
python3 -m venv .venv .venv/bin/pip install -r requirements.txt
-
First run opens browser for OAuth consent:
.venv/bin/python scripts/gmail.py read --limit 3
# Read emails
scripts/gmail.py read --limit 10
scripts/gmail.py read --query "is:unread" --full
# Create draft
scripts/gmail.py draft --to "[email protected]" --subject "Hi" --body "Hello"
scripts/gmail.py draft --reply-to MSG_ID --body "Thanks!"
# Send
scripts/gmail.py send --draft-id DRAFT_ID
scripts/gmail.py send --to "[email protected]" --subject "Hi" --body "Hello"
# Manage
scripts/gmail.py archive --id MSG_ID
scripts/gmail.py trash --id MSG_ID
scripts/gmail.py mark-read --id MSG_ID
# Batch operations
scripts/gmail.py batch-archive --query "from:newsletters@"Run scripts/gmail.py --help for all 24 commands.
This repo follows the Agent Skills spec. Drop it in your skills directory and Claude will discover it via the SKILL.md metadata.
MIT