aiskillstore/gmail-tools

Gmail Tools

Secure Gmail access via IMAP/SMTP with 1Password credential storage. Supports listing, reading, searching, sending, and replying to emails with proper threading and attachments.

When to Use

• Reading and managing Gmail emails
• Sending emails with attachments
• Replying to emails while maintaining thread continuity
• Searching emails using IMAP queries

Prerequisites

1Password Setup

Create a 1Password item with:

• Item name: Any descriptive name (e.g., "Gmail Work Claude", "Gmail Personal")
• username field: Your Gmail address (e.g., [email protected])
• password field: Gmail App Password (NOT your regular password)

Getting a Gmail App Password

1. Go to Google Account Security
2. Enable 2-Factor Authentication if not already enabled
3. Go to "App passwords" (under "2-Step Verification")
4. Generate a new app password for "Mail"
5. Copy the 16-character password to your 1Password item

MCP Server Tools

The plugin provides these MCP tools:

list_emails

List recent emails from an account.

account: "Gmail Work Claude"  # 1Password item name
folder: "INBOX"               # Optional, default: INBOX
limit: 10                     # Optional, default: 10

read_email

Read full email content including threading headers.

account: "Gmail Work Claude"
email_id: "46"                # From list_emails
folder: "INBOX"               # Optional

send_email

Send a new email with optional attachments.

account: "Gmail Work Claude"
to: "[email protected]"
subject: "Hello"
body: "Email content here"
cc: "[email protected]"          # Optional
bcc: "[email protected]"        # Optional
attachments: ["/path/to/file.pdf"]  # Optional

reply_email

Reply to an email, maintaining the thread.

account: "Gmail Work Claude"
email_id: "46"                # Email to reply to
body: "Thanks for your message!"
attachments: ["/path/to/doc.pdf"]  # Optional
folder: "INBOX"               # Optional

search_emails

Search using IMAP syntax.

account: "Gmail Work Claude"
query: "FROM [email protected]"  # or "SUBJECT hello", "UNSEEN", etc.
folder: "INBOX"               # Optional
limit: 10                     # Optional

Standalone Scripts

For CLI usage without MCP, use scripts in scripts/:

List Emails

./scripts/gmail_list.py "Gmail Work Claude" --limit 20
./scripts/gmail_list.py "Gmail Work Claude" --json  # JSON output

Read Email

./scripts/gmail_read.py "Gmail Work Claude" "46"
./scripts/gmail_read.py "Gmail Work Claude" "46" --json

Reply to Email

# Dry run (preview without sending)
./scripts/gmail_reply.py "Gmail Work Claude" "46" \
  --body "Thanks for your email." \
  --attachment ~/document.pdf \
  --dry-run

# Send reply
./scripts/gmail_reply.py "Gmail Work Claude" "46" \
  --body "Thanks for your email." \
  --attachment ~/document.pdf

Email Threading

When using reply_email, the tool automatically:

1. Extracts the original email's Message-ID and References headers
2. Sets In-Reply-To to the original Message-ID
3. Builds proper References header chain
4. Adds RE: prefix to subject if not present
5. Sends to the sender's email address

This ensures replies appear in the same thread in all email clients.

Common IMAP Search Queries

| Query | Description | | ---------------------- | ----------------------------- | | ALL | All messages | | UNSEEN | Unread messages | | FROM "john" | From sender containing "john" | | SUBJECT "meeting" | Subject containing "meeting" | | SINCE "01-Jan-2024" | Messages since date | | BEFORE "01-Jan-2024" | Messages before date | | BODY "keyword" | Body containing "keyword" |

Combine with parentheses: (FROM "john" SUBJECT "meeting")

Troubleshooting

"1Password item not found"

Verify the exact item name in 1Password matches what you're using.

"Authentication failed"

• Ensure you're using an App Password, not your regular Gmail password
• Verify 2FA is enabled on your Google account
• Check the App Password hasn't been revoked

"IMAP not enabled"

Enable IMAP in Gmail Settings → Forwarding and POP/IMAP → Enable IMAP