gmail-cleanup-mcp
Provides tools for Gmail inbox cleanup, enabling trashing emails, bulk deletion, search-and-trash with dry-run preview, managing filters, and extracting unsubscribe information from emails.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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_trashandbatch_trash_emailssilently 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
Tool | Description |
| Move a single email to trash (30-day safety net) |
| Trash up to 500 emails by message ID, processed in batches of 50 |
| Find emails by Gmail query and trash them — supports dry-run preview |
| Create filters to auto-archive, auto-label, auto-delete, or forward |
| List all existing Gmail filters with criteria and actions |
| Remove a Gmail filter by ID |
| Extract |
Related MCP server: Gmail 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.jsonfrom another Gmail MCP server? Skip to step 2 — this server uses the same credential location.
Go to Google Cloud Console
Create a project (or reuse an existing one) and enable the Gmail API
Go to Credentials → Create Credentials → OAuth client ID
Choose Desktop app, download the JSON
Save it as
~/.gmail-mcp/gcp-oauth.keys.json(or placegcp-oauth.keys.jsonin 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 build3. Authenticate
npm run authThis 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
Prompt | What happens |
"Trash all emails from newsletter@spam.com older than 6 months" |
|
"Do a dry run — show me what would get trashed from LinkedIn" |
|
"Create a filter to auto-archive emails from nextdoor.com" |
|
"Check if that marketing email has an unsubscribe link" |
|
How it works with Claude's built-in Gmail
Built-in Gmail connector | This server | |
Search & read | Yes | — |
Draft & send | Yes | — |
Trash emails | — | Yes |
Bulk cleanup | — | Yes (up to 500/call) |
Filter management | — | Yes |
Unsubscribe extraction | — | Yes |
Security
Minimal scopes:
gmail.modify+gmail.settings.basic— the minimum needed for trash and filter operationsTrash, not delete: All deletions use Gmail's trash (30-day recovery window), never permanent delete
Dry-run mode:
search_and_trashcan preview matches before committingRestrictive 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
Variable | Default | Description |
|
| Path to OAuth client keys |
|
| Path to stored credentials |
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage Gmail end-to-end: search, read, send, draft, label, and organize threads. Automate workflow…
Search and triage all your mailboxes; draft replies and campaigns; send only as you allow.
Manage Gmail messages, threads, labels, drafts, and settings from your workflows. Send and organiz…
I do everything related to Gmail and productivity
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive Gmail integration with 25+ tools for intelligent email management, including AI-powered categorization, advanced search and filtering, automated archiving and cleanup, analytics, and secure OAuth2 authentication.298 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Gmail accounts through natural language for tasks like sending, reading, searching, and organizing emails. It supports advanced features including draft management, label operations, and batch actions via secure OAuth 2.0 authentication.MIT
- FlicenseNot gradedqualityDmaintenanceEnables intelligent Gmail management, including email triage, newsletter classification, promotional email cleanup, summarization, filter suggestions, draft replies, and audit logging.-
- AlicenseNot gradedqualityDmaintenanceEnables monitoring shared Google storage quota and recovering Gmail space by scanning cleanup candidates, scoring them deterministically, and requiring review before moving non-protected messages to Trash.MIT