gmail-mcp

Gmail für deinen KI-Assistenten — mehrere Konten gleichzeitig, auf einem Server, der dir gehört.

日本語版 · 简体中文

gmail-mcp verbindet Gmail mit Claude und jedem anderen MCP-Client. Es kann E-Mails durchsuchen und lesen, senden und Allen antworten – mit zitiertem Verlauf –, weiterleiten, Anhänge und Inline-Bilder verarbeiten sowie Entwürfe, Labels und Threads verwalten – und das bei mehreren Google-Konten gleichzeitig.

Es läuft als Remote-Server auf deinem eigenen Cloudflare Worker. So können Claude Code auf einem Laptop, claude.ai im Browser und Claude auf dem Handy dieselbe Verbindung verwenden. Jede Verbindung ist bei einem Google-Konto angemeldet, und das Google-Refresh-Token bleibt in deinem Cloudflare-Konto.

Zwei Dinge führen die Menschen hierher. Die in Claude und Google eingebauten Gmail-Connectors können E-Mails lesen und Entwürfe schreiben, aber nicht senden, und koppeln ein Assistenten-Konto an genau ein Google-Konto. Server, die senden können, sind meist lokale Prozesse – am Schreibtisch in Ordnung, vom Handy aus nicht erreichbar.

Vergleich

google_workspace_mcp ist das vollständigste Projekt hier. Es deckt ganz Workspace ab, nicht nur Gmail, und fügt deine Gmail-Signatur hinzu und zieht Anhänge direkt von einer URL – beides macht gmail-mcp nicht. shinzo-labs/gmail-mcp erreicht über seine 64 Tools außerdem Abwesenheitsassistenten, Stellvertreter und S/MIME; diese liegen unter gmail.settings.*, einem Bereich, den gmail-mcp nie anfragt – und der damit unerreichbar bleibt, egal was mit einer Freigabe passiert.

Zwei Designunterschiede entscheiden über den Rest. Konten per Aufrufargument auszuwählen erlaubt es einer Freigabe, jedes verbundene Postfach zu erreichen; das Binden des Postfachs an die Verbindung bedeutet dagegen, dass ein falsches Argument nichts erreicht. Und die lokalen Server decodieren beim Lesen jedes Teil als UTF-8: ISO-2022-JP- und Shift_JIS-Mails kommen durcheinander an, und lange Nachrichten, die Gmail als Anhang-Blobs ablegt, kommen mit leerem Inhalt zurück.

Bereitstellen

Ungefähr zehn Minuten. Du brauchst ein Cloudflare-Konto, bun und ein Google-Konto. Eine Domain im Cloudflare-Konto ist optional – ohne sie antwortet der Worker unter workers.dev.

1 · Google-OAuth-Client erstellen

PROJECT="gmail-mcp-$(openssl rand -hex 3)"
gcloud auth login
gcloud projects create "$PROJECT" --name="gmail-mcp"
gcloud config set project "$PROJECT"
gcloud services enable gmail.googleapis.com

Für die nächsten beiden Schritte bietet Google keine API an. Deshalb erfolgen sie in der Cloud-Konsole:

• OAuth-Zustimmungsbildschirm → Extern, dann unter Zielgruppe auf App veröffentlichen klicken. Im Testmodus lässt Google jedes Refresh-Token nach 7 Tagen ablaufen, und jede Verbindung stirbt mit ihrem Token. Nach der Veröffentlichung zeigt die App beim Anmelden eine Warnung zur nicht verifizierten App und bedient bis zu 100 Konten.

• Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID → Webanwendung, mit https://<your-host>/callback als autorisierter Weiterleitungs-URI. Client-ID und Secret aufbewahren.

<your-host> ist die Domain, die du auf den Worker zeigst, oder der workers.dev-Hostname, den er andernfalls erhält. Zuerst bereitzustellen und später zurückzukommen, um das auszufüllen, funktioniert – die Anleitung, die der Worker unter / ausliefert, zeigt den genauen Wert.

2 · Worker bereitstellen

Der Button kopiert das Repository in dein GitHub-Konto, erstellt den KV-Namespace und das Durable Object und fragt nach den vier Secrets. Er stellt auf workers.dev bereit; eine benutzerdefinierte Domain wird anschließend unter Einstellungen → Domains & Routen angehängt.

Alternativ über ein Terminal:

git clone https://github.com/mkpoli/gmail-mcp && cd gmail-mcp
bun install
bun run setup

bun run setup fragt, auf welcher Domain geantwortet werden soll, erstellt oder verwendet den OAUTH_KV-Namespace neu, nimmt Client-ID und Secret entgegen, generiert einen Cookie-Schlüssel und stellt bereit. Die ersten beiden Antworten landen in wrangler.local.jsonc, das von git ignoriert wird – wrangler.jsonc nennt weder den Namespace eines Kontos noch die Domain von irgendjemandem, sodass ein Klon überall bereitgestellt werden kann. Das erneute Ausführen von setup, um ein einzelnes Secret zu rotieren, ist sicher.

3 · Einen Client verbinden

Die Felder für Client-ID und Secret leer lassen – MCP-Clients registrieren sich selbst.

claude mcp add --transport http gmail-personal https://<your-host>/mcp
claude mcp add --transport http gmail-work     https://<your-host>/mcp/work

Führe /mcp in Claude Code aus, um jede Verbindung bei ihrem Google-Konto anzumelden. In claude.ai ist es Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen mit derselben URL. Jedes einsegmentige Label funktioniert nach /mcp/, wodurch eine Bereitstellung mehrere Postfächer für Clients bedienen kann, die zwei Server mit gemeinsamer URL ablehnen.

Deine Bereitstellung liefert diese Anleitung unter https://<your-host>/ aus.

Was es kann

whoami search_messages get_message get_thread get_attachment

send_message reply_all forward_message create_draft update_draft send_draft delete_draft list_drafts stage_attachment_begin stage_attachment_append stage_attachment_finish

list_labels create_label update_label delete_label modify_labels modify_thread_labels batch_modify_messages trash_message · untrash_message trash_thread · untrash_thread

Nachrichten verlassen das System so, wie ein Mail-Client sie sendet: Klartext mit einer HTML-Alternative, Dateianhänge und Inline-Bilder, die per cid: referenziert werden, verschachtelt als multipart/mixed › multipart/related › multipart/alternative. Betreffe und Anzeigenamen verwenden RFC 2047, Dateinamen RFC 2231, sodass Japanisch, Chinesisch und Emojis die Reise überstehen.

reply_all liest Reply-To, From, To und Cc des Originals, verwirft die eigene Adresse und jede Adresse, als die du Mail sendest, antwortet von der Adresse, an die der Absender geschrieben hat, führt die References-Kette weiter und zitiert das Original in den Teilen, die du sendest. forward_message reproduziert den weitergeleiteten Umschlag und kann die Dateien des Originals erneut anhängen.

create_draft mit replyToMessageId schreibt die Antwort als Entwurf zum Bearbeiten vor dem Senden: Es tritt dem Thread des Originals bei, übernimmt In-Reply-To und References, leitet die Antwort-an-alle-Empfänger und den Re:-Betreff ab und zitiert das Original. update_draft ändert nur die Felder, die übergeben werden; Empfänger, Text, in einem beliebigen Client von Hand hinzugefügte Dateien und der Thread, auf den der Entwurf antwortet, werden zurückgelesen und beibehalten. Eine Datei, deren Base64 nicht durch Tool-Argumente passt, wird stattdessen gestuft: stage_attachment_begin gibt eine Upload-URL zurück, die die Rohbytes in einem einzigen curl -T entgegennimmt, stage_attachment_append nimmt Base64 in Blöcken entgegen, und jedes attachments-Feld akzeptiert die resultierende stagingId.

Das Lesen ist bewusst begrenzt: Nachrichten- und Thread-Bodies haben Zeichenbudgets, eine gesamte Antwort hat eine Byte-Obergrenze, und ein Anhang wird nur dann inline zurückgegeben, wenn er klein genug zum Lesen bleibt. Ein langer Mailinglisten-Thread oder eine große Datei kommt beschnitten mit einem Hinweis darauf zurück, statt den Kontext des Assistenten zu füllen.

So funktioniert es

Zwei OAuth-Flows treffen sich in einem Worker. Der MCP-Client authentifiziert sich gegenüber dem Worker; der Worker authentifiziert sich gegenüber Google in deinem Namen. Keine Seite hält die Anmeldedaten der anderen.

sequenceDiagram
    autonumber
    participant C as MCP client<br/>(Claude Code · claude.ai)
    participant W as Worker<br/>(OAuthProvider + McpAgent)
    participant G as Google<br/>(OAuth + Gmail API)

    C->>W: POST /register (dynamic client registration)
    C->>W: GET /authorize (PKCE challenge)
    W->>C: approval dialog
    C->>G: consent screen — pick the account
    G->>W: GET /callback?code=…
    W->>W: allowlist check on the verified email
    W->>G: exchange code → access + refresh token
    W->>C: MCP access token (Google tokens sealed inside the grant)
    C->>W: POST /mcp — tools/call
    W->>G: Gmail REST (token refreshed as needed)
    G->>W: message / thread / label data
    W->>C: tool result

Erstellt mit

• TypeScript auf Cloudflare Workers – Durable Objects halten jeweils eine MCP-Sitzung, KV hält die OAuth-Grants

• Hono – Routing für die OAuth-Endpunkte, den Google-Callback und die Einrichtungsseite unter /

• @cloudflare/workers-oauth-provider – der OAuth-2.1-Server, gegen den sich MCP-Clients registrieren

• agents – McpAgent, der MCP-Transport über Durable Objects

• @modelcontextprotocol/sdk mit Zod – Tool-Definitionen und Argumentvalidierung

• Bun, Biome, Wrangler – installieren, testen, linten, bereitstellen

Gmail selbst wird über einfaches fetch gegen die REST-API aufgerufen. Das offizielle googleapis-SDK setzt Node voraus und bringt weit mehr mit, als ein Worker ausliefern sollte, daher leben Nachrichtenaufbau, MIME-Parsing und Token-Erneuerung stattdessen in src/gmail.ts und src/utils.ts.

Endpunkte

Wer sich anmelden kann

ALLOWED_EMAILS entscheidet, geprüft gegen die Adresse, die Google als verifiziert meldet – nach der Zustimmung, bevor ein Grant existiert.

Jeder Grant erreicht nur das Postfach, das ihn authentifiziert hat. Diese Liste zu erweitern erweitert also nie den Zugriff auf bereits verbundene Postfächer. * zu setzen lässt Fremde deine Bereitstellung und das Kontingent deines Google-Clients für ihre eigene Mail nutzen.

Grenzen

Zwei Obergrenzen verhindern, dass eine gemeinsam genutzte Bereitstellung ausgeschöpft wird, beide in wrangler.jsonc gesetzt:

Im Free-Tarif von Workers gilt eine weitere Obergrenze: 50 ausgehende Anfragen pro Aufruf. Ein breiter Lesevorgang verbraucht eine pro Nachricht, daher sollten search_messages und list_drafts dort maxResults auf 45 oder darunter setzen; darüber hinaus kommen die Überschüsse als Fehler pro Nachricht zurück, nicht als Ergebnisse. Der kostenpflichtige Tarif erlaubt 1000.

Erhöhen Sie einen davon und stellen Sie erneut bereit. Der Rate-Limiter von Cloudflare liest seine Obergrenze zur Build-Zeit aus der Bindung, daher ist das simple.limit auf jedem die einzige Stelle, die es ändert. Eine Einzelbenutzer-Bereitstellung kann beide unverändert lassen – die normale Nutzung durch den Assistenten liegt weit darunter.

Sicherheit

Self-Hosting verschiebt die Vertrauensfrage, anstatt sie zu beseitigen – hier also die Einordnung.

• Ihre Tokens bleiben Ihre. Refresh-Tokens sind innerhalb ihrer OAuth-Genehmigung in Ihrem KV-Namespace verschlüsselt. Das Durable Object einer Sitzung hält das eine Stunde gültige Zugriffstoken, und das MCP-Agent-Framework behält dort eine Kopie der Genehmigung, solange das Objekt lebt, einschließlich des Refresh-Tokens. Beide Speicher sind Ihr eigenes Cloudflare-Konto, im Ruhezustand verschlüsselt. E-Mail wird nie gespeichert – sie wird nur durchgereicht.

• Eine Sitzung, ein Postfach. Die MCP-Sitzung ist an das Konto gebunden, das sie geöffnet hat, sodass eine Genehmigung für ein Postfach nicht über eine ausgeliehene Sitzungs-ID auf ein anderes wirken kann.

• Scope-Minimalismus. gmail.modify deckt Lesen, Senden, Labels und Papierkorb ab. Es schließt dauerhaftes Löschen und alle gmail.settings.* aus, sodass automatische Weiterleitungsregeln und Filter-Exfiltration – die klassischen Hintertüren für Postfächer – außerhalb dessen liegen, was ein gestohlenes Grant tun könnte. Zwei Nur-Lese-Scopes werden daneben angefordert, userinfo.email und userinfo.profile: Sie sind der Weg, über den die Whitelist und die Sitzungsbindung wissen, welches Konto angemeldet ist, und sie erreichen keine E-Mail.

• Header können nicht eingeschmuggelt werden. Jeder ausgehende Header-Wert wird abgelehnt, wenn er CR, LF oder NUL enthält, sodass kein Argument aus seinem eigenen Feld ausbrechen kann, um eines anzuhängen – etwa ein Bcc in einer Betreffzeile. Medientypen werden validiert, und zitierter Verlauf wird HTML-escaped. Was dies nicht tut, ist die Argumente selbst zu überwachen: bcc ist ein echter Parameter, sodass ein Modell, das einer in einem Nachrichtentext versteckten Anweisung folgt, es dennoch ausfüllen könnte, und der Genehmigungsdialog Ihres Clients bleibt die Kontrolle darüber.

• Zugriff kann entzogen werden. Das Einschränken von ALLOWED_EMAILS stoppt neue Anmeldungen. Der Zugriff eines einzelnen Kontos wird unter myaccount.google.com/connections widerrufen. Das Rotieren des Google-Client-Secrets macht jedes Grant sofort ungültig.

Der Worker entschlüsselt E-Mails im Speicher, während er eine Anfrage bedient, wie es jeder gehostete Relay tun muss. Wenn das für ein bestimmtes Postfach nicht akzeptabel ist, führen Sie für dieses einen lokalen MCP-Server aus.

Wie es getestet wurde

253 Unit-Tests decken die Nachrichtenerstellung ab (MIME-Verschachtelung, RFC-2047-Faltung, RFC-2231-Dateinamen, CR/LF-Ablehnung, Base64-Umbruch), die Textextraktion über Zeichensätze hinweg, das Verfassen von Antworten und Weiterleitungen, die Google-Token-Abläufe, die Anmelde-Whitelist, die CSRF- und State-Binding-Prüfungen, die die Browserseite der Anmeldung schützen, sowie die Tools selbst gegen ein Ersatz-Gmail – Sitzungsbesitz, Empfängerzusammenstellung, Anhangsauswahl und was eine teilweise fehlgeschlagene Leseoperation zurückgibt.

Darüber hinaus wurde jedes Tool gegen echte Gmail-Konten ausgeführt, wobei ein separates Konto prüfte, was ankam:

Entwicklung

bun run dev     # wrangler dev on :8788
bun run check   # biome + tsc
bun test        # 253 unit tests
bun run assets  # regenerate the light and dark diagrams
bun run deploy

Fragen und Fehler

Eröffnen Sie ein Issue.

Lizenz

Copyright © 2026 mkpoli. Veröffentlicht unter der MIT-Lizenz.

src/workers-oauth-utils.ts ist abgeleitet von der remote-mcp-github-oauth-Demo in cloudflare/ai, Copyright © 2025 Cloudflare, Inc., verwendet unter der MIT-Lizenz. Siehe THIRD-PARTY.md.