Gmail Labeler

Installation Guide

Set up the Gmail Labeler skill in Claude Code or Cursor in a few steps.

Prerequisites

  • Claude Code or Cursor - AI coding assistant with MCP support
  • Gmail MCP Server - Community MCP connector for Gmail API
  • Google Cloud Project - With Gmail API enabled and OAuth 2.0 credentials
  • Node.js - For running the MCP server

Step 1: Google Cloud Setup

Create a Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Navigate to APIs & Services → Library
  4. Search for "Gmail API" and enable it

Create OAuth 2.0 Credentials

  1. Go to APIs & Services → Credentials
  2. Click "Create Credentials" → "OAuth client ID"
  3. Application type: "Desktop app"
  4. Download the credentials JSON file
  5. Save it to a secure location (e.g., ~/.config/gmail-credentials.json)

Step 2: Install Gmail MCP Server

Install the community Gmail MCP server globally:

$
npm install -g @modelcontextprotocol/server-gmail

Note: Replace with the actual MCP server package name from the community registry.

Step 3: Configure MCP Server

Add the Gmail MCP server to your Claude Code or Cursor settings:

Claude Code

Edit ~/.config/claude/mcp_settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gmail"],
      "env": {
        "GOOGLE_CREDENTIALS": "/path/to/your/credentials.json"
      }
    }
  }
}

Cursor

Edit Cursor settings JSON (Preferences → MCP):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gmail"],
      "env": {
        "GOOGLE_CREDENTIALS": "/path/to/your/credentials.json"
      }
    }
  }
}

Replace /path/to/your/credentials.json with the actual path to your downloaded credentials file.

Step 4: Install the Skill

Clone the repository and copy the skill to your agents directory:

$ git clone https://github.com/rNLKJA/gmail-labeler.git
$ cd gmail-labeler
$ mkdir -p ~/.agents/skills
$ cp -r original/.agents/skills/gmail-labeler ~/.agents/skills/

Step 5: First Run (Dry Run)

Always test with a dry run first:

  1. 1.
    Restart Claude Code/Cursor to load the MCP server
  2. 2.
    Open a conversation and ask: "Label my inbox (dry run mode)"
  3. 3.
    Review the plan - The skill will show what labels it would create and which emails would be labeled
  4. 4.
    Confirm if the plan looks good: "Apply those labels for real"

Tips & Best Practices

Use a Test Account First

Set up the skill on a test Gmail account before running it on your main inbox.

Review the Logs

Check LOG.md after each run to see exactly what was changed.

Customize Provider Rules

Edit provider-rules.md to add your own providers and categories.

Generate Gmail Filters

After labeling, ask to generate filter XML for automatic future labeling.