gmail-mcp

Gmail-Connector für MCP-Clients. Ein Server, viele Gmail-Konten über OAuth-Refresh-Tokens. Sendet echtes MIME (Dateipfad-Anhänge, Live-Signaturen, Nachweis nach dem Versand). Liest und organisiert E-Mails, ohne Megabytes an Base64 in das Modell zu kippen.

Kein Wrapper um das von Google gehostete Gmail-MCP – der Gmail-Connector erstellt RFC822 auf dem Host und spricht direkt mit gmail.googleapis.com.

Features

• Multi-Konto-OAuth – Postfächer mit accounts_add hinzufügen; Tokens werden lokal gespeichert (Modus 0600)

• Senden / Antworten / Weiterleiten – serverseitig erstelltes MIME, nur Dateipfade aus dem Outbox-Ordner, 25-MB-Grenze, Idempotenzschlüssel, Nachweis bei Erfolg

• Lesen / Organisieren – Suche (Threads + Paginierung), Thread/Nachricht abrufen, Labels, Archivieren/Papierkorb, Entwürfe

• Anhänge – aus ~/Outbox senden (konfigurierbar); nach ~/Inbox herunterladen (konfigurierbar)

• Doppelter Transport – stdio für lokale Umgebungen; Streamable HTTP hinter einem Gateway für entfernte Clients

Related MCP server: Gmail MCP Server

Anforderungen

• Python 3.12+ (Entwicklung nutzt 3.13 via pyenv)

• Google Cloud Desktop-OAuth-Client (Client-ID + Secret)

• macOS für die enthaltenen LaunchAgent-Skripte (HTTP-Dienst); Linux funktioniert für manuelle Ausführungen

Schnellstart

git clone https://github.com/iXanadu/gmcp.git
cd gmcp

# Python 3.12+ (example with pyenv)
pyenv virtualenv 3.13 gmail-mcp-3.13
pyenv local gmail-mcp-3.13
pip install -e '.[dev]'

# Config (see examples/)
cp examples/.env.example .env
cp examples/.keys.example .keys
chmod 600 .keys

# Sanity check
gmail-doctor

Trage deine Google-OAuth-Zugangsdaten und ein HTTP-Bearer-Token in .keys ein, bevor du den HTTP-Transport ausführst.

Google Cloud Console (einmalig)

Du benötigst einen Desktop-OAuth-Client – keinen Dienstaccount und keine domänenweite Delegierung.

Beim ersten accounts_add fragt Google nach der Zustimmung. Die Scopes sind im Server festgelegt: E-Mails lesen/senden/organisieren sowie die Send-as-Signatur lesen (nicht zwischengespeichert).

Kein Benutzername/Passwort, kein App-Passwort und kein eingefügtes Refresh-Token im Chat.

Postfach verbinden (accounts_add)

accounts_add öffnet einen Browser für die Google-Zustimmung. Es läuft nur auf dem stdio-Transport (gmail-mcp), nicht über HTTP.

gmail-mcp   # stdio — required for accounts_add and accounts_remove

Rufe accounts_add von deinem MCP-Client auf. Wenn die Zustimmung abgeschlossen ist, speichert der Server die von Google zurückgegebene Gmail-Adresse; diese Adresse ist der account-Schlüssel für alle anderen Tools.

Tokens landen in ~/.config/gmail-mcp/tokens/ (Modus 0600). Kopiere dieses Verzeichnis bei Bedarf auf jeden anderen Host, auf dem derselbe Server läuft.

Headless-Server (kein lokaler Browser)

Der OAuth-Callback ist http://127.0.0.1:8767/oauth/callback. Eine Maschine ohne Display benötigt für die Google-Anmeldeseite trotzdem irgendwo einen Browser. Zwei gängige Muster:

A – SSH-Portweiterleitung (Zustimmung auf deinem Laptop)

Starte auf dem Headless-Host stdio MCP / accounts_add. Von deinem Laptop aus:

ssh -L 8767:127.0.0.1:8767 user@headless-host

Öffne die vom Server ausgegebene Autorisierungs-URL (oder löse accounts_add über deinen MCP-Client aus, während der Tunnel aktiv ist). Der Callback erreicht über den Tunnel 127.0.0.1:8767 auf dem Headless-Host.

Wait, I just typed "127.0.0.1:8767" as "127.0.0.1:8767" but in the sentence above I accidentally wrote "127.0.0.1:8767" with a typo "8767"? Let's ensure.

Original: 127.0.0.1:8767. My sentence: "Der Callback erreicht über den Tunnel 127.0.0.1:8767 auf dem Headless-Host." Need correct. In my draft I wrote "127.0.0.1:8767" but I need ensure not "8767" vs "8767". The callback port is 8767. Yes original http://127.0.0.1:8767/oauth/callback. Actually original is http://127.0.0.1:8767/oauth/callback. Port is 8767 (four digits: 8-7-6-7? Wait original: http://127.0.0.1:8767/oauth/callback. Let's check source: "Add redirect URI http://127.0.0.1:8767/oauth/callback" Yes port is 8767 (eight-seven-six-seven? No, 8767: 8 7 6 7). Wait "8767" digits: 8,7,6,7. Yes. My text "8767" is correct if I write 8767. In previous line I wrote "8767" but accidentally "8767"? I'll be careful.

Also "Headless-Host" correct. In my line above I wrote "Auf dem Headless-Host." Good.

Let's restart final from that point to avoid typos.

Continue:

ssh -L 8767:127.0.0.1:8767 user@headless-host

Öffne die vom Server ausgegebene Autorisierungs-URL (oder löse accounts_add über deinen MCP-Client aus, während der Tunnel aktiv ist). Der Callback erreicht über den Tunnel 127.0.0.1:8767 auf dem Headless-Host.

B – Zustimmung auf einem Desktop, Tokens kopieren

Führe accounts_add einmal auf einem Mac oder PC mit Browser und derselben .env / .keys aus. Kopiere nach der Zustimmung ~/.config/gmail-mcp/tokens/ auf den Produktionshost (gleiche Pfade, Modus 0600). Keine erneute Zustimmung erforderlich, es sei denn, Google widerruft das Refresh-Token.

Deployment-Layout

Typische Produktionsaufteilung:

┌─────────────────────┐         ┌──────────────────────────┐
│  Operator machine   │         │  MCP server (Linux/macOS) │
│  (browser for OAuth)│         │  gmail-mcp-http           │
│  accounts_add       │  copy   │  127.0.0.1:8879           │
│  token files ───────┼────────►│  + .env / .keys           │
└─────────────────────┘  tokens └───────────┬──────────────┘
                                            │
                              Cloudflare / gateway / TLS
                                            │
                                    Hand / remote MCP client

• Setze den Laptop des Betreibers nicht für MCP HTTP dem öffentlichen Internet aus. HTTP bindet auf dem Server an Loopback (127.0.0.1:8879); ein Reverse-Proxy beendet TLS und leitet an diesen Port weiter.

• OAuth findet dort statt, wo ein Browser existiert (Betreibermaschine oder SSH-Tunnel). Die Token-JSON-Dateien werden auf den Server kopiert.

• Das Gateway zeigt auf den Server-Hostnamen, den du kontrollierst (z. B. mcp.example.com), nicht auf die OAuth-Workstation.

• Generiere ein langes zufälliges GMAIL_MCP_HTTP_BEARER_TOKEN; das Gateway präsentiert es als Authorization: Bearer ….

Nach dem Deployment: gmail-doctor, ./scripts/start.sh (macOS LaunchAgent) oder deine eigene systemd-Unit, dann accounts_list über HTTP, um die Tokens zu bestätigen.

Konfiguration

Nicht sensible Einstellungen stehen in .env; Geheimnisse in .keys (committe niemals eine der beiden Dateien, wenn sie befüllt sind). Siehe examples/.env.example und examples/.keys.example.

Führe gmail-doctor aus, nachdem du die Konfiguration geändert hast.

Transporte

stdio (lokal)

gmail-mcp

Registriert alle Tools, einschließlich accounts_add und accounts_remove.

Binde es in die MCP-Konfiguration von Cursor / Claude Code ein, mit der gmail-mcp-Binärdatei aus der venv und cwd auf das Repository gesetzt (damit .env / .keys geladen werden).

Streamable HTTP (Gateway)

gmail-mcp-http

Bindet standardmäßig an 127.0.0.1:8879. Erfordert Authorization: Bearer <GMAIL_MCP_HTTP_BEARER_TOKEN>; Anfragen ohne gültiges Token erhalten 401.

Manuelle Zulassungsliste (nur HTTP): Lese-/Organisations-Tools plus send, reply, forward, draft_create, draft_send, accounts_list und gmail_status. Die Kontoverwaltung bleibt auf stdio.

macOS-Dienst (Benutzer-LaunchAgent)

./scripts/start.sh    # install plist → ~/Library/LaunchAgents, load
./scripts/stop.sh
./scripts/restart.sh

Passe die Pfade in launchd/com.gmail-mcp.plist an, wenn sich dein Checkout oder pyenv-Name unterscheidet. Logs liegen unter logs/.

Führe gmail-mcp-http unter Linux mit systemd und demselben Loopback-Bind aus – siehe Deployment-Layout oben.

Tools

Jedes Tool außer accounts_list, accounts_add und gmail_status erfordert ein account-Argument (die Gmail-Adresse).

Senderegeln (Zusammenfassung)

• Anhänge: { "path": "/absolute/or/under/outbox/file.pdf" } – kein Inline-Base64

• Live-Gmail-Signatur wird beim Senden angehängt (nicht zwischengespeichert)

• Optionaler footer nach der Signatur

• Gibt einen Nachweis zurück: Größen, hrefs, ok false → Tool-Fehler (z. B. abgeschnittener Anhang oder google.com/url-Umschreibung)

Tests

pytest tests/ -v

Nutzt simuliertes Gmail-HTTP; kein echtes Postfach erforderlich.

Spezifikation

Produktanforderungen: docs/specs/gmail-mcp-spec.md

Lizenz

Apache-2.0