Gmail Storage & Cleanup MCP

Ein fokussiertes lokales MCP-Plugin für Codex und Claude Code, das den gemeinsamen Google-Speicher überwacht und dabei hilft, Gmail-Speicherplatz mithilfe eines deterministischen, überprüfungsorientierten Aufräum-Workflows zurückzugewinnen.

Es prüft das Google-Speicherkontingent, findet große Gmail-Aufräumkandidaten, erklärt jede Sicherheitsentscheidung und verlangt eine Bestätigung, bevor E-Mails in den Papierkorb verschoben werden. Es löscht E-Mails niemals endgültig. Dieses Repository enthält keine Anmeldedaten.

Warum dieses Projekt existiert

Das offizielle Gmail-Plugin ist die bessere Wahl für allgemeine Postfachaufgaben wie das Durchsuchen von E-Mails, das Zusammenfassen von Threads, das Verfassen von Antworten, das Weiterleiten und das Anwenden von Labels.

Dieses Projekt konzentriert sich bewusst auf ein anderes Problem: zu verhindern, dass einem Google-Konto der Speicherplatz ausgeht, ohne dabei wichtige E-Mails blind zu löschen.

Dieser Vergleich beschreibt den dokumentierten Schwerpunkt jedes Plugins, nicht jede Funktion, die ein vorgelagerter Connector in Zukunft hinzufügen könnte.

Related MCP server: Gmail Guardian

Installation

Voraussetzungen: Python 3.12+, Git und ein Google-Konto mit Gmail.

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

1. Google-Anmeldedaten erstellen

In der Google Cloud Console:

1. Erstellen Sie ein Projekt und aktivieren Sie die Gmail API und die Google Drive API.

2. Konfigurieren Sie die Google Auth Platform. Verwenden Sie für persönliche Tests External/Testing und fügen Sie Ihre Gmail-Adresse als Testbenutzer hinzu.

3. Erstellen Sie einen OAuth-Client mit dem Anwendungstyp Desktop-App.

4. Öffnen Sie .env und fügen Sie die generierten Werte hinzu:

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

Einmalig autorisieren:

.venv/bin/python -m app.auth_cli

Das lokale Token wird in work/google-token.json geschrieben. Sowohl diese Datei als auch .env werden von Git ignoriert.

2. In Codex installieren

Aus dem Repository-Stammverzeichnis:

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

Starten Sie eine neue Codex-Aufgabe und fragen Sie dann: „Prüfe meinen Google-Speicher und finde Gmail-Aufräumkandidaten zur Überprüfung.“

3. In Claude Code installieren

Aus dem Repository-Stammverzeichnis:

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

Starten Sie nach der Installation eine neue Claude Code-Sitzung.

Fokussierte Tools

• get_storage_quota — gemeinsame Google-Speichernutzung

• scan_cleanup_candidates — schreibgeschützte Gmail-Erkundung und deterministische Bewertung

• get_candidate_details — ein Ergebnis aus dem letzten Scan überprüfen

• move_message_to_trash — verschiebt eine bestätigte, nicht geschützte Nachricht in den Papierkorb

Zu den geschützten Labels gehören STARRED, IMPORTANT, SENT und DRAFT. Mehrdeutige E-Mails verbleiben in der Überprüfung. Eine Nachricht muss aus dem letzten Scan stammen, bevor sie verschoben werden kann, und geschützte Nachrichten können vom Tool nicht verarbeitet werden. Das Plugin leert den Papierkorb nicht und löscht keine Nachrichten dauerhaft.

Entwicklung

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

Plugin-Quellcode: plugins/gmail-mcp-tool/

Bewusste Abgrenzung

• Speicherprognosen und geplante Kontingentprüfungen

• Transparentere Aufräumrichtlinien und Regelanpassung

• Aggregierte Schätzungen des zurückgewinnbaren Speicherplatzes und Aufräumberichte

• Optionale Klassifizierung für mehrdeutige Kandidaten, ohne die deterministischen Schutzmechanismen zu umgehen

Die allgemeine Postfachsuche, E-Mail-Zusammenfassungen, das Verfassen von Antworten und das Weiterleiten bleiben absichtlich dem offiziellen Gmail-Plugin überlassen.

Sicherheit

Nehmen Sie niemals .env, heruntergeladene OAuth-JSON-Dateien oder work/google-token.json in ein Commit auf. Führen Sie vor der Veröffentlichung von Änderungen python scripts/security_check.py aus. Falls Anmeldedaten jemals in ein Commit gelangen, widerrufen und rotieren Sie sie sofort – es reicht nicht, sie aus dem neuesten Commit zu entfernen.

MIT-lizenziert.