# 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.**

| Capability | Official Gmail plugin | Gmail Storage & Cleanup MCP |
| --- | --- | --- |
| Search, read, summarize, reply, and forward | Yes | Not its goal |
| Gmail labels and everyday inbox organization | Yes | Not its goal |
| Shared Google storage quota and free-space monitoring | Not a documented core capability | Yes, through Drive `storageQuota` |
| Rank cleanup candidates using Gmail `sizeEstimate` | Not a documented core capability | Yes |
| Deterministic, test-covered safety scoring | No project-specific policy | Yes |
| Protected/review/safe decision with reasons | No project-specific policy | Yes |
| Review-before-trash enforcement inside the tool | General confirmation safeguards | Yes, candidate-bound and explicit |
| Permanent deletion | No | No |

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

## Install

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

```bash
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](https://console.cloud.google.com/):

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:

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

Authorize once:

```bash
.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:

```bash
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:

```bash
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

```bash
.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.