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 suchen und lesen, senden und Allen antworten mit zitierter Historie, weiterleiten, Anhänge und Inline-Bilder verarbeiten sowie Entwürfe, Labels und Threads verwalten – über mehrere Google-Konten gleichzeitig.

Es läuft als Remote-Server auf deinem eigenen Cloudflare Worker, sodass dieselbe Verbindung von Claude Code auf einem Laptop, claude.ai im Browser und Claude auf dem Handy beantwortet wird. Jede Verbindung meldet sich bei einem Google-Konto an, und das Google-Refresh-Token bleibt in deinem Cloudflare-Konto.

Zwei Dinge treiben die Leute hierher. Die in Claude und Google integrierten Gmail-Connectors lesen E-Mails und schreiben Entwürfe, können aber nicht senden und halten ein Google-Konto pro Assistentenkonto. Server, die senden können, sind normalerweise lokale Prozesse – am Schreibtisch in Ordnung, vom Handy aus unsichtbar.

So schneidet es im Vergleich ab

google_workspace_mcp ist das vollständigste Projekt hier. Es deckt ganz Workspace ab statt nur Gmail, und es fügt deine Gmail-Signatur an und holt Anhänge direkt von einer URL – beides macht gmail-mcp nicht. shinzo-labs/gmail-mcp erreicht Abwesenheitsantworten, Delegierte und S/MIME über seine 64 Tools; diese liegen unter gmail.settings.*, einem Bereich, den gmail-mcp nie anfordert, sodass sie außerhalb seiner Reichweite bleiben, egal was mit einer Berechtigung passiert.

Zwei Designentscheidungen entscheiden über den Rest. Das Weiterleiten von Konten über ein Aufrufargument lässt eine Berechtigung jedes verbundene Postfach berühren, während das Binden des Postfachs an die Verbindung bedeutet, dass ein falsches Argument nichts erreicht. Und beim Lesen dekodieren die lokalen Server jeden Teil als UTF-8: ISO-2022-JP- und Shift_JIS-Mails kommen verstümmelt an, und lange Nachrichten, die Gmail als Anhangs-Blobs speichert, kommen mit leerem Textkörper zurück.

Related MCP server: littlebird-mail

Bereitstellen

Ungefähr zehn Minuten. Du brauchst ein Cloudflare-Konto, bun und ein Google-Konto. Eine Domain auf dem Cloudflare-Konto ist optional – ohne eine antwortet der Worker auf 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

Google bietet keine API für die nächsten beiden Schritte, daher finden sie in der Cloud-Konsole statt:

• OAuth-Zustimmungsbildschirm → External, 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 vor nicht verifizierten Apps 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 Geheimnis aufbewahren.

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

2 · Worker bereitstellen

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

Stattdessen ü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, nimmt Client-ID und Geheimnis entgegen, generiert einen Cookie-Schlüssel und stellt bereit. Diese 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 Geheimnis zu rotieren, ist sicher.

3 · Einen Client verbinden

Lassen Sie die Felder für Client-ID und Geheimnis leer – 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ühren Sie /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/, so bedient eine Bereitstellung mehrere Postfächer für Clients, die zwei Server mit derselben URL ablehnen.

Ihre Bereitstellung liefert diesen Leitfaden 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 über cid: referenziert werden, verschachtelt als multipart/mixed › multipart/related › multipart/alternative. Betreff 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 Ihre eigene Adresse und jede Adresse, als die Sie E-Mails senden, antwortet von der Adresse, an die der Absender geschrieben hat, führt die References-Kette mit und zitiert das Original in den Teilen, die Sie senden. forward_message reproduziert den weitergeleiteten Umschlag und kann die Dateien des Originals erneut anhängen.

create_draft mit replyToMessageId schreibt die Antwort als Entwurf, der vor dem Senden bearbeitet werden kann: Er tritt dem Thread des Originals bei, führt In-Reply-To und References mit, leitet die Antwort-an-alle-Empfänger und den Betreff Re: ab und zitiert das Original. update_draft ändert nur die Felder, die ihm übergeben werden; Empfänger, Text, von Hand in einem beliebigen Client 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 gestaged: stage_attachment_begin gibt eine Upload-URL zurück, die die rohen Bytes 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 entsprechenden Hinweis zurück, anstatt den Kontext des Assistenten zu füllen.

So funktioniert es

Zwei OAuth-Abläufe treffen sich in einem Worker. Der MCP-Client authentifiziert sich gegenüber dem Worker; der Worker authentifiziert sich gegenüber Google in Ihrem Namen. Keine Seite besitzt 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 Setup-Seite 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 liegen Nachrichtenaufbau, MIME-Parsing und Token-Refresh 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. Eine Erweiterung dieser Liste erweitert also niemals den Zugriff auf bereits verbundene Postfächer. Die Einstellung * erlaubt Fremden, Ihre Bereitstellung und das Kontingent Ihres Google-Clients für ihre eigene E-Mail zu nutzen.

Grenzen

Zwei Obergrenzen verhindern, dass eine gemeinsame Bereitstellung ausgeschöpft wird, beide in wrangler.jsonc festgelegt:

Im Free-Plan von Workers gilt eine weitere Obergrenze: 50 ausgehende Anfragen pro Aufruf. Ein umfassender Lesezugriff verbraucht eine pro Nachricht, daher benötigen search_messages und list_drafts dort maxResults von höchstens 45; darüber kommen die Überschüsse als Fehler pro Nachricht zurück statt als Ergebnisse. Der kostenpflichtige Plan erlaubt 1000.

Erhöhen Sie einen der Werte und stellen Sie erneut bereit. Der Ratenbegrenzer von Cloudflare liest seine Obergrenze zur Build-Zeit aus der Bindung, daher ist das simple.limit an jeder Stelle die einzige Stelle, an der es geändert wird. Eine Bereitstellung für einen einzelnen Benutzer kann beide Werte unverändert lassen – die normale Assistentennutzung bleibt weit darunter.

Sicherheit

Self-Hosting verschiebt die Vertrauensfrage, anstatt sie zu beseitigen. Hier also, wo alles liegt.

• Ihre Tokens bleiben Ihre. Aktualisierungstokens werden in Ihrer KV-Namespace innerhalb ihrer OAuth-Genehmigung verschlüsselt. Ein Durable Object einer Sitzung hält das eine Stunde gültige Zugriffstoken, und das MCP-Agent-Framework bewahrt eine Kopie der Genehmigung dort auf, solange das Objekt lebt, einschließlich des Aktualisierungstokens. Beide Speicher befinden sich in Ihrem eigenen Cloudflare-Konto, im Ruhezustand verschlüsselt. E-Mails werden nie gespeichert – sie werden nur durchgereicht.

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

• Minimaler Umfang. gmail.modify deckt Lesen, Senden, Beschriftungen und Papierkorb ab. Es schließt dauerhaftes Löschen und den gesamten Bereich gmail.settings.* aus, sodass automatische Weiterleitungsregeln und Filter-Exfiltration – die klassischen Hintertüren in Postfächern – außerhalb dessen liegen, was eine gestohlene Genehmigung tun könnte. Zwei schreibgeschützte Bereiche werden daneben angefordert, userinfo.email und userinfo.profile: Über sie erfahren die Zulassungsliste und die Sitzungsbindung, welches Konto angemeldet ist, und sie erreichen keine E-Mails.

• Kopfzeilen können nicht eingeschleust werden. Jeder ausgehende Kopfzeilenwert wird abgelehnt, wenn er CR, LF oder NUL enthält. So kann kein Argument aus seinem eigenen Feld ausbrechen, 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 im Nachrichtentext versteckten Anweisung folgt, es trotzdem ausfüllen könnte – und die Genehmigungsaufforderung Ihres Clients bleibt die Kontrolle darüber.

• Der Zugriff kann entzogen werden. Durch das Einschränken von ALLOWED_EMAILS werden neue Anmeldungen gestoppt. Der Zugriff eines einzelnen Kontos wird unter myaccount.google.com/connections widerrufen. Durch das Rotieren des Google-Client-Geheimnisses werden alle Genehmigungen auf einmal ungültig.

Der Worker entschlüsselt E-Mails im Arbeitsspeicher, 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.

So wurde getestet

253 Komponententests decken die Nachrichtenerstellung ab (MIME-Verschachtelung, RFC-2047-Umbruch, RFC-2231-Dateinamen, CR/LF-Ablehnung, Base64-Umbruch), Textextraktion über Zeichensätze hinweg, Antwort- und Weiterleitungszusammenstellung, die Google-Token-Abläufe, die Anmelde-Zulassungsliste, die CSRF- und Statusbindungsprüfungen, die die Browserseite der Anmeldung schützen, sowie die Tools selbst gegen ein Stellvertreter-Gmail – Sitzungsbesitz, Empfängerzusammenstellung, Anhangsauswahl und was ein teilweise fehlgeschlagener Lesezugriff 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.