Gmail Storage & Cleanup MCP

A focused local MCP plugin for Codex and Claude Code that monitors shared Google storage and helps recover Gmail space through a deterministic, review-first cleanup workflow.

It checks Google storage quota, finds large Gmail cleanup candidates, explains every safety decision, and requires confirmation before moving mail to Trash. It never permanently deletes mail. No credentials are included in this repository.

Why this exists

The official Gmail plugin is the better choice for general inbox work such as searching mail, summarizing threads, drafting replies, forwarding, and applying labels.

This project deliberately focuses on a different problem: preventing a Google account from running out of storage without blindly deleting important email.

This comparison describes the documented focus of each plugin, not every capability an upstream connector may add in the future.

Related MCP server: Gmail MCP Server

Install

Requirements: Python 3.12+, Git, and a Google account with Gmail.

git clone https://github.com/ashutoshchaubeypm/Gmail-MCP-tool.git
cd Gmail-MCP-tool
./scripts/setup.sh

1. Create Google credentials

In Google Cloud Console:

1. Create a project and enable Gmail API and Google Drive API.

2. Configure Google Auth Platform. For personal testing, use External/Testing and add your Gmail address as a test user.

3. Create an OAuth client with application type Desktop app.

4. Open .env and add the generated values:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Authorize once:

.venv/bin/python -m app.auth_cli

The local token is written to work/google-token.json. Both it and .env are ignored by Git.

2. Install in Codex

From the repository root:

codex plugin marketplace add "$PWD"
codex plugin add gmail-mcp-tool@personal

Start a new Codex task, then ask: “Check my Google storage and find Gmail cleanup candidates for review.”

3. Install in Claude Code

From the repository root:

claude plugin marketplace add "$PWD"
claude plugin install gmail-mcp-tool@gmail-mcp-tool

Start a new Claude Code session after installation.

Focused tools

• get_storage_quota — shared Google storage usage

• scan_cleanup_candidates — read-only Gmail discovery and deterministic scoring

• get_candidate_details — review one result from the latest scan

• move_message_to_trash — moves one confirmed, non-protected message to Trash

Protected labels include STARRED, IMPORTANT, SENT, and DRAFT. Ambiguous mail stays in review. A message must come from the latest scan before it can be moved, and protected messages cannot be actioned by the tool. The plugin does not empty Trash or permanently delete messages.

Development

.venv/bin/python scripts/security_check.py
.venv/bin/python -m pytest -q

Plugin source: plugins/gmail-mcp-tool/

Deliberate scope

• Storage forecasting and scheduled quota checks

• More transparent cleanup policies and rule customization

• Aggregate recovery estimates and cleanup reports

• Optional classification for ambiguous candidates, without bypassing deterministic protections

General inbox search, email summaries, reply drafting, and forwarding are intentionally left to the official Gmail plugin.

Security

Never commit .env, downloaded OAuth JSON, or work/google-token.json. Before publishing changes, run python scripts/security_check.py. If credentials are ever committed, revoke and rotate them immediately—removing them from the latest commit is not enough.

MIT licensed.