Gmail Skill

Read and search Gmail messages using IMAP with App Passwords. Supports multiple accounts.

Features

List inbox messages with filters
Search emails by sender, subject, or content
Read full email content
Browse folders/labels
Multiple Gmail accounts support
Works with any AI coding agent

Requirements

macOS or Linux with bash
Python 3
Google account with 2FA enabled

Installation

cd skills/gmail
./install.sh

This installs to ~/.claude/skills/gmail/.

Setup

1. Enable 2FA (if not already enabled)

Go to https://myaccount.google.com/security and enable 2-Step Verification.

2. Create an App Password

Go to https://myaccount.google.com/apppasswords
Select app: Mail
Select device: Other (enter "Gmail CLI")
Click Generate
Copy the 16-character password (no spaces)

3. Configure

~/.claude/skills/gmail/config.sh setup

Enter your Gmail address and App Password when prompted.

4. Test

~/.claude/skills/gmail/gmail me

Multi-Account Setup

To add multiple Gmail accounts, edit ~/.claude/skills/gmail/.env:

# Account: work
GMAIL_ACCOUNT_WORK_EMAIL="work@company.com"
GMAIL_ACCOUNT_WORK_APP_PASSWORD="xxxx xxxx xxxx xxxx"

# Account: personal
GMAIL_ACCOUNT_PERSONAL_EMAIL="personal@gmail.com"
GMAIL_ACCOUNT_PERSONAL_APP_PASSWORD="yyyy yyyy yyyy yyyy"

# Optional: set default account
GMAIL_DEFAULT_ACCOUNT="work"

Then use with --account or -a flag:

~/.claude/skills/gmail/gmail --account work list --unread
~/.claude/skills/gmail/gmail -a personal search "from:friend@gmail.com"

Usage

Commands

# List accounts
~/.claude/skills/gmail/gmail accounts

# Profile
~/.claude/skills/gmail/gmail me                     # Account info
~/.claude/skills/gmail/gmail labels                 # List folders

# Messages
~/.claude/skills/gmail/gmail list                   # List inbox (10 messages)
~/.claude/skills/gmail/gmail list --limit 5         # Limit results
~/.claude/skills/gmail/gmail list --unread          # Unread only
~/.claude/skills/gmail/gmail list --label "[Gmail]/Sent Mail"  # Sent folder
~/.claude/skills/gmail/gmail get <messageId>        # Read message
~/.claude/skills/gmail/gmail search "query"         # Search messages

# With specific account
~/.claude/skills/gmail/gmail --account work list --unread
~/.claude/skills/gmail/gmail -a personal search "from:friend@gmail.com"

Search Examples

# From specific sender
~/.claude/skills/gmail/gmail search "from:boss@company.com"

# Subject contains keyword
~/.claude/skills/gmail/gmail search "subject:invoice"

# Unread messages
~/.claude/skills/gmail/gmail search "is:unread"

# Starred messages
~/.claude/skills/gmail/gmail search "is:starred"

# Text in body
~/.claude/skills/gmail/gmail search "meeting agenda"

Search Syntax

Query	Description
`from:email`	From sender
`to:email`	To recipient
`subject:word`	Subject contains
`is:unread`	Unread messages
`is:starred`	Starred messages
`<text>`	Search in body

Agent Integration

After installation, use with your AI agent:

/gmail

Or ask naturally:

"Check my unread emails"
"Check my work email inbox"
"Search for emails from john@example.com in my personal account"
"Read the email about the meeting"

Files

~/.claude/skills/gmail/
├── .env          # Credentials (chmod 600)
├── gmail         # Main script
├── config.sh     # Configuration
└── SKILL.md      # Skill definition

Security

Credentials stored with chmod 600 (owner read/write only)
App Passwords can be revoked at any time from Google settings
This skill is read-only - cannot send, delete, or modify emails

Troubleshooting

"Login failed"

Verify your email and App Password are correct
Make sure 2FA is enabled on your Google account
Try creating a new App Password

"Connection refused"

Check your internet connection
Gmail IMAP might be temporarily unavailable

License

MIT