Gmail Cleanup MCP Server

Ein spezialisierter Model Context Protocol-Server für die Bereinigung des Gmail-Posteingangs – E-Mails in den Papierkorb verschieben, Filter verwalten und Abmelde-Links extrahieren. Entwickelt, um den integrierten Gmail-Connector von Anthropic zu ergänzen, der Lesen, Suchen, Entwurf und Senden übernimmt.

Gepatchter Fork von dcerniglia/gmail-cleanup-mcp (MIT-lizenziert). Dieser Fork behebt einen Fehler, bei dem search_and_trash und batch_trash_emails Fehler stillschweigend verschluckten, anstatt es erneut zu versuchen – das gleichzeitige Senden von 50 Papierkorb-Anfragen konnte das Rate-Limit von Gmail auslösen und einen ~halben Batch ohne angezeigten Fehler verwerfen. Jetzt verarbeiten beide Tools kleinere Batches, führen einen Backoff durch, wiederholen automatisch und melden den tatsächlichen Fehler pro fehlgeschlagener Nachricht.

Werkzeuge

Related MCP server: Gmail AutoAuth MCP Server

Voraussetzungen

• Node.js 18+

• Ein Google Cloud-Projekt mit aktivierter Gmail API

• OAuth 2.0-Anmeldedaten (Desktop-App-Typ)

Einrichtung

1. Google Cloud OAuth

Haben Sie bereits ~/.gmail-mcp/gcp-oauth.keys.json von einem anderen Gmail-MCP-Server? Überspringen Sie Schritt 2 – dieser Server verwendet denselben Speicherort für Anmeldedaten.

1. Gehen Sie zu Google Cloud Console

2. Erstellen Sie ein Projekt (oder verwenden Sie ein vorhandenes) und aktivieren Sie die Gmail API

3. Gehen Sie zu Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID

4. Wählen Sie Desktop-App und laden Sie das JSON herunter

5. Speichern Sie es als ~/.gmail-mcp/gcp-oauth.keys.json (oder platzieren Sie gcp-oauth.keys.json im Projektverzeichnis – es wird beim ersten Start automatisch kopiert)

2. Installation und Build

git clone https://github.com/davidcerniglia/gmail-cleanup-mcp.git
cd gmail-cleanup-mcp
npm install
npm run build

3. Authentifizierung

npm run auth

Dadurch wird ein Browser für die Google-OAuth-Zustimmung geöffnet. Die Anmeldedaten werden unter ~/.gmail-mcp/credentials.json mit 0600-Berechtigungen gespeichert (nur für den Besitzer).

4. Zu Claude Desktop hinzufügen

Fügen Sie zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu (macOS):

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

Oder für Claude Code fügen Sie es zu .claude/settings.json hinzu:

{
  "mcpServers": {
    "gmail-cleanup": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-cleanup-mcp/dist/index.js"]
    }
  }
}

Anwendungsbeispiele

So funktioniert es mit dem integrierten Gmail-Connector von Claude

Sicherheit

• Minimale Scopes: gmail.modify + gmail.settings.basic – das Minimum, das für Papierkorb- und Filteroperationen erforderlich ist.

• Papierkorb statt Löschen: Alle Löschvorgänge erfolgen über den Papierkorb von Gmail (30-tägiges Wiederherstellungsfenster), niemals durch endgültiges Löschen.

• Dry-run-Modus: search_and_trash kann Übereinstimmungen vor dem Ausführen als Vorschau anzeigen.

• Restriktive Dateiberechtigungen: Anmeldedaten werden mit 0600 gespeichert (nur Lesen/Schreiben für den Besitzer).

• Keine Anhangsverarbeitung: Keinerlei Path-Traversal-Risiko.

• Kein Dateisystemzugriff außer auf die Speicherung von Anmeldedaten in ~/.gmail-mcp/.

Umgebungsvariablen

Lizenz

MIT