Gmail Cleanup MCP Server

A focused Model Context Protocol server for Gmail inbox cleanup — trash emails, manage filters, and extract unsubscribe links. Designed to complement Anthropic's built-in Gmail connector, which handles read, search, draft, and send.

Patched fork of dcerniglia/gmail-cleanup-mcp (MIT licensed). This fork fixes a bug where search_and_trash and batch_trash_emails silently dropped failures instead of retrying — firing 50 concurrent trash requests could trip Gmail's rate limit and drop ~half a batch with no error shown. Now both tools batch smaller, back off, auto-retry, and report the real error per failed message.

Tools

Related MCP server: Gmail AutoAuth MCP Server

Prerequisites

• Node.js 18+

• A Google Cloud project with the Gmail API enabled

• OAuth 2.0 credentials (Desktop app type)

Setup

1. Google Cloud OAuth

Already have ~/.gmail-mcp/gcp-oauth.keys.json from another Gmail MCP server? Skip to step 2 — this server uses the same credential location.

1. Go to Google Cloud Console

2. Create a project (or reuse an existing one) and enable the Gmail API

3. Go to Credentials → Create Credentials → OAuth client ID

4. Choose Desktop app, download the JSON

5. Save it as ~/.gmail-mcp/gcp-oauth.keys.json (or place gcp-oauth.keys.json in the project directory — it will be copied automatically on first run)

2. Install & Build

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. Authenticate

npm run auth

This opens a browser for Google OAuth consent. Credentials are saved to ~/.gmail-mcp/credentials.json with 0600 permissions (owner-only).

4. Add to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

Or for Claude Code, add to .claude/settings.json:

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

Usage Examples

How it works with Claude's built-in Gmail

Security

• Minimal scopes: gmail.modify + gmail.settings.basic — the minimum needed for trash and filter operations

• Trash, not delete: All deletions use Gmail's trash (30-day recovery window), never permanent delete

• Dry-run mode: search_and_trash can preview matches before committing

• Restrictive file permissions: Credentials stored with 0600 (owner read/write only)

• No attachment handling: Zero path traversal risk

• No filesystem access beyond credential storage in ~/.gmail-mcp/

Environment Variables

License

MIT