Skip to main content
skill CX Codex

gmail · glebis — skill for Claude Code and five more platforms

Skill for searching Gmail messages via API with filters for sender, date, status and attachments. Works on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode.

MIT 258 installs ★ 414 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add glebis/claude-skills --skill gmail -a claude-code
Open on GitHub

What gmail does

Connects through OAuth authentication in Google Cloud. Before first use, create a project in console.cloud.google.com, enable the Gmail API, configure the OAuth Consent Screen and add your Gmail as a test user. Save your credentials to ~/.gmail_credentials/credentials.json and run python3 scripts/gmail_search.py auth.

Search supports Gmail query syntax: free text like “meeting notes”, flags like --from, --subject, --unread, date filters (--after 2024/01/01). Results print as Markdown or JSON. The download MESSAGE_ID command saves attachments to ~/Downloads/gmail_attachments/ or a custom path.

Test user tokens expire after seven days. Production requires Google verification.

What it helps with

  • find messages from a specific sender or about a topic
  • download an attachment from an email
  • filter for unread or starred messages
  • search email text using Gmail syntax
  • export search results to JSON

Example prompts for the agent

  • Search Gmail for emails from [email protected] from the last month
  • Download the attachment from message 18abc123def
  • Find all unread emails with invoice in the subject and download attachments

How to install gmail

1Skills CLI (Vercel)

npx skills add glebis/claude-skills --skill gmail -a claude-code

2Manually: put the files in place

~/.claude/skills/gmail/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gmail/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gmail

How do I install gmail for Claude Code?

Run npx skills add glebis/claude-skills --skill gmail -a claude-code. Then edit ~/.claude/skills/gmail/SKILL.md.

What does the gmail skill do?

It searches Gmail for messages by keywords, sender, date, status and attachments. It can download attachments and return results as Markdown or JSON.

How do I get credentials for Gmail?

Create a project in Google Cloud Console, enable Gmail API, configure OAuth Consent Screen with your test user, publish the app, create an OAuth client ID of type Desktop, save the JSON to ~/.gmail_credentials/credentials.json, then run python3 scripts/gmail_search.py auth.

Source text

SKILL.md · MIT
---
name: gmail
description: This skill should be used when searching, fetching, or downloading emails from Gmail. Use for queries like "search Gmail for...", "find emails from John", "show unread emails", "emails about project X", or "download attachment from email".
---

# Gmail Search Skill

Search and fetch emails via Gmail API with flexible query options and output formats.

## Prerequisites

Credentials must be configured in `~/.gmail_credentials/`. Run `setup` to check status:

```bash
python3 scripts/gmail_search.py setup
```

### Obtaining Gmail API Credentials

#### 1. Create Google Cloud Project

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Click project dropdown -> "New Project"
3. Name it (e.g., "Gmail Agent Skill") -> Create

#### 2. Enable Gmail API

1. Navigate to "APIs & Services" -> "Library"
2. Search for "Gmail API"
3. Click it and press "Enable"

#### 3. Configure OAuth Consent Screen

1. Go to "OAuth consent screen" (left sidebar)
2. Choose "External" user type
3. Fill in required fields:
   - App name: Gmail Agent Skill
   - User support email: your email
   - Developer email: your email
4. Click "Save and Continue", skip Scopes
5. On "Test users" page, add your Gmail address
6. Complete all steps

#### 4. Publish the Test App

**Important:** Without this step, you'll get "Error 403: access_denied".

1. Go back to "OAuth consent screen"
2. Under "Publishing status", click "Publish App"
3. Confirm the dialog

This keeps the app in test mode (not production) but allows your test users to authenticate. You'll see an "unverified app" warning during login - click "Advanced" -> "Go to Gmail Agent Skill (unsafe)" to proceed.

**Note:** Test tokens expire after 7 days. Production requires Google verification.

#### 5. Create OAuth Credentials

1. Go to "Credentials" (left sidebar)
2. Click "Create Credentials" -> "OAuth client ID"
3. Select "Desktop app" as application type
4. Name it (e.g., "Gmail Agent Client")
5. Click "Create"

#### 6. Get Your Credentials

1. Client ID will be displayed - copy it
2. Client Secret: Click the download icon or view details to get the secret

#### 7. Save Credentials

Create `~/.gmail_credentials/credentials.json`:

```json
{
  "installed": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}
```

#### 8. Authenticate

```bash
python3 scripts/gmail_search.py auth
```

This opens a browser. Click through the "unverified app" warning ("Advanced" -> "Go to Gmail Agent Skill"), approve access, and you're ready.

## Quick Start

```bash
# Check setup status
python3 scripts/gmail_search.py setup

# Authenticate (opens browser)
python3 scripts/gmail_search.py auth

# Search emails
python3 scripts/gmail_search.py search "meeting notes"

# Search with filters
python3 scripts/gmail_search.py search --from "[email protected]" --unread
```

## Commands

### Setup

Check configuration status:

```bash
python3 scripts/gmail_search.py setup
python3 scripts/gmail_search.py setup --json
```

### Authenticate

Authenticate with Gmail (opens browser for OAuth):

```bash
python3 scripts/gmail_search.py auth
```

### Scope

View or change API permission scope:

```bash
# View current scope
python3 scripts/gmail_search.py scope

# Change scope (requires re-auth)
python3 scripts/gmail_search.py scope --set readonly
python3 scripts/gmail_search.py scope --set modify
python3 scripts/gmail_search.py scope --set full
```

**Available scopes:**
- `readonly` - Read emails only (default, recommended)
- `modify` - Read + modify labels, mark read/unread
- `full` - Full access including delete

### Search

Search emails with free-text query or filters:

```bash
# Free-text search (uses Gmail search syntax)
python3 scripts/gmail_search.py search "project deadline"
python3 scripts/gmail_search.py search "from:[email protected] subject:invoice"

# Using helper flags
python3 scripts/gmail_search.py search --from "[email protected]"
python3 scripts/gmail_search.py search --to "[email protected]"
python3 scripts/gmail_search.py search --subject "Weekly Report"
python3 scripts/gmail_search.py search --label "INBOX"
python3 scripts/gmail_search.py search --label "work"

# Date filters (YYYY/MM/DD format)
python3 scripts/gmail_search.py search --after 2024/01/01
python3 scripts/gmail_search.py search --before 2024/12/31
python3 scripts/gmail_search.py search --after 2024/01/01 --before 2024/06/30

# Status filters
python3 scripts/gmail_search.py search --unread
python3 scripts/gmail_search.py search --starred
python3 scripts/gmail_search.py search --has-attachment

# Combined filters
python3 scripts/gmail_search.py search "invoice" --from "billing@" --has-attachment --after 2024/01/01

# Limit results
python3 scripts/gmail_search.py search "meeting" --limit 50

# Include full body (default shows snippet only)
python3 scripts/gmail_search.py search "contract" --full

# Include attachment info
python3 scripts/gmail_search.py search --has-attachment --attachments

# JSON output
python3 scripts/gmail_search.py search "project" --json
```

### Download Attachments

Download attachments from a specific message:

```bash
# Download to default location (~/Downloads/gmail_attachments/)
python3 scripts/gmail_search.py download MESSAGE_ID

# Download to custom directory
python3 scripts/gmail_search.py download MESSAGE_ID --output /path/to/folder

# JSON output
python3 scripts/gmail_search.py download MESSAGE_ID --json
```

Get message ID from search results (shown in output).

### Labels

List all available Gmail labels:

```bash
python3 scripts/gmail_search.py labels
python3 scripts/gmail_search.py labels --json
```

## Output Formats

### Markdown (default)

```markdown
# Gmail Search Results (3 messages)

## Weekly Report
**From:** [email protected]
**To:** [email protected]
**Date:** Mon, 25 Nov 2024 10:00:00 +0000
**ID:** `18abc123def`

> Here's the weekly report summary...

---
```

### JSON

Add `--json` flag for structured output:

```json
[
  {
    "id": "18abc123def",
    "thread_id": "18abc123def",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Weekly Report",
    "date": "Mon, 25 Nov 2024 10:00:00 +0000",
    "snippet": "Here's the weekly report summary...",
    "labels": ["INBOX", "UNREAD"]
  }
]
```

## Gmail Search Syntax

The skill supports Gmail's native search syntax in free-text queries:

| Operator | Example | Description |
|----------|---------|-------------|
| `from:` | `from:[email protected]` | From specific sender |
| `to:` | `to:[email protected]` | To specific recipient |
| `subject:` | `subject:meeting` | In subject line |
| `label:` | `label:work` | Has specific label |
| `has:attachment` | `has:attachment` | Has attachments |
| `filename:` | `filename:pdf` | Attachment filename |
| `is:unread` | `is:unread` | Unread messages |
| `is:starred` | `is:starred` | Starred messages |
| `after:` | `after:2024/01/01` | After date |
| `before:` | `before:2024/12/31` | Before date |
| `newer_than:` | `newer_than:7d` | Within last N days |
| `older_than:` | `older_than:1m` | Older than N months |
| `in:` | `in:inbox` | In specific folder |
| `OR` | `from:john OR from:jane` | Either condition |
| `-` | `-label:spam` | Exclude |
| `""` | `"exact phrase"` | Exact match |

## Example User Requests

| User says | Command |
|-----------|---------|
| "Search Gmail for meeting notes" | `search "meeting notes"` |
| "Find emails from John" | `search --from "john"` |
| "Show unread emails" | `search --unread` |
| "Emails about the project from last month" | `search "project" --after 2024/10/01` |
| "Invoices with attachments" | `search "invoice" --has-attachment` |
| "Read the full email about contract" | `search "contract" --full --limit 1` |
| "Download attachments from that email" | `download MESSAGE_ID` |
| "What labels do I have?" | `labels` |
| "Starred emails from boss" | `search --from "boss" --starred` |
| "Is Gmail configured?" | `setup` |

## Dependencies

```bash
pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib
```

## Files

- `~/.gmail_credentials/credentials.json` - OAuth client credentials
- `~/.gmail_credentials/token.pickle` - Cached auth token
- `~/.gmail_credentials/scope.txt` - Current scope setting

© glebis · MIT · glebis/claude-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

gmail by other authors comes first.

gmail sanjay3290 Searches, reads, and sends emails through Gmail directly from the agent interface. Helpful for triaging the inbox, managing drafts, and organizing labels. CX Codex +1 528installs gmail membrane This skill connects an agent to Gmail through Membrane for mail, drafts, threads, and labels. Use it when a workflow needs Gmail actions from the terminal. CX Codex +1 782installs gws-gmail-send official googleworkspace Exposes gws gmail +send to the agent. Sends Gmail messages with attachments, CC/BCC, HTML body and sender aliases. CX Codex +1 76,800installs recipe-create-gmail-filter official googleworkspace recipe-create-gmail-filter — a skill that builds Gmail filters to apply labels, stars, and folder rules automatically. Runs via gws commands and requires the gws-gmail skill loaded first. CX Codex +1 32,400installs gmail-skill idanbeck Reads, searches and sends Gmail messages, and looks up Google contacts. Useful when the agent has to triage a mailbox or prepare a draft. CX Codex +1 3,600installs gmail-access terrylica The gmail-access skill connects the agent to a Gmail command-line client so it can pull messages, search a mailbox, save what it finds and stage drafts. Handy when the thread you need sits next to the code you are working on. CX Codex +1 137installs Multi-Account Gmail cunicopia-dev Multi-Account Gmail — an MCP server that keeps several Gmail accounts authorized at once, so your agent can read, search, label and draft across all of them. CX Codex +1 ★ 6repo stars gmail-mcp mkpoli Connects Gmail accounts to your AI assistant using a personal Cloudflare Worker. It reads, sends, and handles message threads across multiple mailboxes. CX Codex +1 ★ 9repo stars

From the same set51

The whole set →
brand-agency brand-agency pushes Agency's neobrutalist look into slides, SVG, HTML and social images: fixed palette, font stack, hard-shadow rules. CX Codex +1 276installs doctorg doctorg is a Claude Code skill that answers health, nutrition, training and sleep questions by checking trusted sources and grading the strength of evidence for each claim. CX Codex +1 265installs tdd tdd runs test-driven development cycles with strict context separation across subagents. Useful for writing clean features and reproducing bugs. CX Codex +1 262installs youtube-transcript The youtube-transcript skill pulls subtitles and video metadata from YouTube, saves them as Markdown with YAML frontmatter into an Obsidian vault. CX Codex +1 258installs transcript-analyzer transcript-analyzer extracts decisions, action items, opinions, unresolved questions, and domain terms from meeting transcripts using Cerebras AI. CX Codex +1 258installs zoom Skill to create, update, and list Zoom meetings, and access cloud recordings via Zoom API. Search recordings with transcripts, summaries, and download links. CX Codex +1 252installs fathom Skill to retrieve meetings, transcripts, AI summaries, and action items directly from Fathom API. Use it to sync meeting recordings and transcripts into your coding workflow. CX Codex +1 249installs github-gist A skill to quickly publish files and notes as GitHub Gist. Use it when you need to share code, create a shareable snippet link, or upload markdown without extra steps. CX Codex +1 246installs

More in the catalog

Project sponsors

Companies that keep this analytics open