gmail-mcp

Ein Multi-Account-Gmail-MCP-Server für KI-Agenten (Claude Code und alles andere, was MCP spricht), mit einem Designziel, das über allem steht: Der Agent darf frei lesen und entwerfen, aber ein Mensch muss jeden Versand genehmigen.

Gebaut, weil die gehosteten Gmail-Connectors jeweils nur ein Konto binden und ohne Hürden senden. Dieser Server bindet beliebig viele Gmail-Konten hinter kurzen Aliasen (work, school, ...) und teilt Fähigkeiten nach Risiko auf:

Der Server ist absichtlich als gmail-accounts (nicht gmail) registriert: Wenn Sie auch einen gehosteten Gmail-Connector betreiben, können nahezu identische Toolnamen dazu führen, dass ein Agent das falsche Postfach liest und ein fälschlich negatives Ergebnis mit hoher Sicherheit meldet.

So funktioniert das Sende-Gate

1. Der Agent legt einen Entwurf an und bittet Sie um Genehmigung.

2. Sie führen gmail-approve in Ihrem eigenen Terminal aus, prüfen die exakte RFC822-Nutzlast und erhalten ein Einmal-Token, das an den Inhalts-Hash dieses Entwurfs gebunden ist.

3. Der Agent ruft das Sende-Tool mit dem Token auf. Falscher Entwurf, bearbeiteter Entwurf, wiederverwendetes Token, abgelaufenes Token: alles wird abgelehnt.

Das Sende-Tool trägt außerdem anthropic/requiresUserInteraction, sodass Claude Code einen Menschen selbst im bypassPermissions-Modus auffordert. Die Token-CLI ist eine Verriegelung gegen Fehlbedienung; die Eingabeaufforderung der Harness ist die durchgesetzte Grenze.

Related MCP server: Gmail Multi-Inbox MCP Server

Setup

Erfordert Python 3.12+ und uv.

1. Google Cloud OAuth-Client

Erstellen Sie ein Projekt unter console.cloud.google.com, aktivieren Sie die Gmail API, erstellen Sie eine OAuth-Client-ID vom Typ Desktop-App und laden Sie die JSON-Datei herunter nach:

~/.config/gmail-mcp/client_secret.json

2. Deklarieren Sie Ihre Konten

~/.config/gmail-mcp/accounts.json:

{
  "accounts": [
    { "alias": "personal", "email": "alice.personal@gmail.com" },
    { "alias": "work",     "email": "alice.work@gmail.com" }
  ]
}

Das spätere Hinzufügen eines Kontos ist eine Konfigurationsänderung plus ein Authentifizierungslauf; die Datei wird bei jedem Aufruf neu gelesen, daher ist kein Neustart erforderlich.

3. Autorisieren Sie jedes Konto

uv sync
scripts/auth-all.sh          # runs the OAuth flow once per alias, skips done ones

Jede Autorisierung wird gegen ihren Alias geprüft: Das Autorisieren des falschen Google-Kontos im Browser wird erkannt und abgelehnt, nicht stillschweigend gespeichert.

4. Bei Claude Code registrieren

claude mcp add gmail-accounts -- uv run --directory /path/to/gmail-mcp --frozen --no-sync gmail-mcp

Tägliche Nutzung

Jedes Tool akzeptiert einen account-Alias. Bitten Sie den Agenten zum Beispiel, „in work nach dem Rechnungs-Thread zu suchen“ oder „auf personal eine Antwort zu entwerfen“. Wenn es an der Zeit ist zu senden:

gmail-approve            # lists pending sends, shows the payload, mints a token

Gesundheitscheck:

uv run gmail-mcp-health

Sicherheitshinweise

• Geheimnisse gelangen nie ins Repository: client_secret.json und die Token pro Konto liegen in ~/.config/gmail-mcp/ (überschreibbar mit GMAIL_MCP_CONFIG).

• Alle Konfigurationsschreibvorgänge sind atomar (tmp + fsync + rename); ein Absturz mitten im Schreiben hinterlässt nie eine unvollständige Datei.

• stdout ist der JSON-RPC-Kanal; nichts im Paket darf print() verwenden (durchgesetzt von ruff T201), sodass Diagnosemeldungen das Protokoll nicht korrumpieren können.

Tests

uv run pytest