Gmail Storage & Cleanup MCP

「Codex」と「Claude Code」向けの特化したローカルMCPプラグインで、共有Googleストレージを監視し、決定的でレビュー優先のクリーンアップワークフローを通じてGmailの容量回復を支援します。

Googleストレージの割り当て量をチェックし、サイズの大きいGmailクリーンアップ候補を特定し、安全性に関するすべての判断を説明し、メールをゴミ箱に移動する前に確認を要求します。メールを完全に削除することはありません。このリポジトリには認証情報は含まれていません。

なぜこれが存在するのか

公式Gmailプラグインは、メールの検索、スレッドの要約、返信の下書き、転送、ラベルの適用などの一般的な受信トレイ作業にはより適しています。

このプロジェクトは意図的に別の問題に焦点を当てています：重要なメールをむやみに削除することなく、Googleアカウントのストレージ不足を防ぐことです。

この比較は、各プラグインの文書化された焦点を説明するものであり、アップストリームのコネクタが将来追加する可能性のあるすべての機能を説明するものではありません。

Related MCP server: Gmail MCP Server

インストール

前提条件：Python 3.12+、Git、およびGmailを使用するGoogleアカウント。

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

1. Google認証情報を作成する

Google Cloud Consoleで：

1. プロジェクトを作成し、Gmail APIとGoogle Drive APIを有効にします。

2. Google Auth Platformを設定します。個人でのテストには、外部/テスト中を使用し、Gmailアドレスをテストユーザーとして追加します。

3. アプリケーションタイプデスクトップアプリでOAuthクライアントを作成します。

4. .envを開き、生成された値を追加します：

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

一度認証を実行します：

.venv/bin/python -m app.auth_cli

ローカルトークンはwork/google-token.jsonに書き込まれます。このトークンと.envはどちらもGitで無視されます。

2. Codexにインストールする

リポジトリのルートから：

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

新しいCodexタスクを開始し、次のように依頼します：「私のGoogleストレージを確認して、レビュー用のGmailクリーンアップ候補を見つけてください。」

3. Claude Codeにインストールする

リポジトリのルートから：

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

インストール後、新しいClaude Codeセッションを開始します。

特化したツール

• get_storage_quota — 共有Googleストレージの使用量

• scan_cleanup_candidates — 読み取り専用のGmail検出と決定的なスコアリング

• get_candidate_details — 最新のスキャンから1件の結果をレビュー

• move_message_to_trash — 確認済みで保護されていない1件のメッセージをゴミ箱に移動

保護対象ラベルにはSTARRED、IMPORTANT、SENT、DRAFTが含まれます。あいまいなメールはレビューに残ります。メッセージは最新のスキャンに由来するものでなければ移動できず、保護されたメッセージはツールで操作できません。このプラグインはゴミ箱を空にしたり、メッセージを完全に削除したりすることはありません。

開発

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

プラグインのソース：plugins/gmail-mcp-tool/

意図的な範囲

• ストレージ予測とスケジュールされた割り当て量チェック

• より透過的なクリーンアップポリシーとルールのカスタマイズ

• 集計された回復見積もりとクリーンアップレポート

• 決定的な保護を迂回することなく、あいまいな候補に対するオプションの分類

一般的な受信トレイの検索、メールの要約、返信の下書き、転送は、意図的に公式Gmailプラグインに委ねられています。

セキュリティ

.env、ダウンロードしたOAuth JSON、work/google-token.jsonは決してコミットしないでください。変更を公開する前に、python scripts/security_check.pyを実行してください。認証情報をコミットしてしまった場合は、すぐに失効させてローテーションしてください。最新のコミットから削除するだけでは不十分です。

MITライセンスです。