gmail-mcp

Gmail für Ihren KI-Assistenten – mehrere Konten gleichzeitig, auf einem eigenen Server.

日本語版 · 简体中文

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 entfernter Server auf Ihrem eigenen Cloudflare Worker, sodass dieselbe Verbindung von Claude Code auf einem Laptop, claude.ai in einem Browser und Claude auf einem Telefon aus antwortet. Jede Verbindung meldet sich bei einem Google-Konto an, und das Google-Refresh-Token verbleibt in Ihrem Cloudflare-Konto.

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

Vergleich

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

Related MCP server: Gmail MCP Server

Bereitstellung

Etwa zehn Minuten. Sie benötigen ein Cloudflare-Konto, bun und ein Google-Konto. Eine Domain im 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 stellt für die nächsten beiden Schritte keine API zur Verfügung, daher erfolgen sie in der Cloud Console:

• OAuth consent screen → External, dann unter Audience auf Publish app klicken. Wenn es im Modus Testing bleibt, läuft jeder Refresh-Token nach 7 Tagen ab und jede Verbindung stirbt mit ihrem Token. Bei Veröffentlichung zeigt die App beim Anmelden eine Warnung wegen nicht verifizierter App und bedient bis zu 100 Konten.

• Credentials → Create credentials → OAuth client ID → Web application, mit https://<your-host>/callback als autorisierte Weiterleitungs-URI. Behalten Sie die Client-ID und das Secret.

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

2 · Deploy the Worker

Der Button kopiert das Repository in Ihr GitHub-Konto, erstellt den KV-Namespace und das Durable Object und fragt nach den vier Geheimnissen. Es wird auf workers.dev bereitgestellt; eine benutzerdefinierte Domain wird anschließend unter Settings → Domains & Routes hinzugefügt.

From a terminal instead:

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 die Client-ID und das Secret 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 jemandem, sodass ein Klon überall bereitgestellt werden kann. Das erneute Ausführen von setup, um ein einzelnes Secret zu rotieren, ist sicher.

3 · Connect a client

Lassen Sie die Felder für Client-ID und Secret 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 in ihr Google-Konto einzuloggen. In claude.ai ist es Settings → Connectors → Add custom connector mit derselben URL. Jedes einsegmentige Label funktioniert nach /mcp/, wodurch eine Bereitstellung mehrere Postfächer für Clients bedienen kann, die zwei Server ablehnen, die sich eine URL teilen.

Ihre Bereitstellung stellt diese Anleitung unter https://<your-host>/ bereit.

What it can do

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 werden so versendet, wie ein Mailclient 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 Emoji die Reise überstehen.

reply_all liest die Reply-To-, From-, To- und Cc-Felder des Originals, verwirft Ihre eigene Adresse und jede Adresse, von der Sie E-Mails senden, antwortet von der Adresse, an die der Absender geschrieben hat, führt die References-Kette weiter und zitiert das Original in den von Ihnen gesendeten Teilen. 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: Es tritt dem Thread des Originals bei, führt In-Reply-To und References weiter, 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, manuell in einem 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 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 Threadtexte 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 wird abgeschnitten mit einem entsprechenden Hinweis zurückgegeben, anstatt den Kontext des Assistenten zu füllen.

How it works

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

Built with

• 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, bei dem 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 enthält weit mehr, als ein Worker ausliefern sollte, daher befinden sich Nachrichtenaufbau, MIME-Parsing und Token-Refresh stattdessen in src/gmail.ts und src/utils.ts.

Endpoints

Who can sign in

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

Jeder Grant erreicht nur das Postfach, das ihn authentifiziert hat, daher erweitert das Vergrößern dieser Liste niemals den Zugriff auf bereits verbundene Postfächer. Die Einstellung * erlaubt Fremden, Ihre Bereitstellung und Ihr Google-Client-Kontingent für ihre eigene E-Mail zu nutzen.

Limits

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

Im Free-Plan von Workers gilt eine weitere Obergrenze: 50 ausgehende Anfragen pro Aufruf. Ein breiter Lesevorgang verbraucht eine pro Nachricht, daher benötigen search_messages und list_drafts dort maxResults von 45 oder weniger; darüber hinaus wird der Überschuss als Fehler pro Nachricht zurückgegeben, nicht als Ergebnisse. Der kostenpflichtige Plan erlaubt 1000.

Erhöhen Sie eine der beiden Grenzen und stellen Sie erneut bereit. Der Ratenbegrenzer von Cloudflare liest seine Obergrenze zur Build-Zeit aus der Bindung, daher ist das simple.limit auf jeder der einzige Ort, der sie ändert. Eine Einzelbenutzer-Bereitstellung kann beide in Ruhe lassen – die normale Assistentennutzung liegt weit darunter.

Sicherheit

Self-Hosting verschiebt die Vertrauensfrage eher, als dass es sie beseitigt, daher finden Sie hier eine Übersicht über die gesamte Situation.

• Ihre Tokens bleiben Ihre. Aktualisierungstokens werden innerhalb ihrer OAuth-Genehmigung in Ihrem KV-Namespace verschlüsselt. Das Durable Object einer Sitzung enthält das eine Stunde gültige Zugriffstoken, und das MCP-Agent-Framework behält dort eine Kopie der Genehmigung für die Lebensdauer des Objekts, einschließlich des Aktualisierungstokens. Beide Speicher sind Ihr eigener Cloudflare-Account, verschlüsselt im Ruhezustand. E-Mails werden nie gespeichert – sie passieren nur.

• Eine Sitzung, ein Postfach. Die MCP-Sitzung ist an den Account gebunden, der sie geöffnet hat, sodass eine Genehmigung für ein Postfach nicht über eine geliehene Sitzungs-ID auf ein anderes einwirken kann.

• Minimaler Umfang. gmail.modify umfasst Lesen, Senden, Labels und Papierkorb. Es schließt dauerhaftes Löschen und alle gmail.settings.* aus, wodurch Weiterleitungsregeln und Filter-Exfiltration – die klassischen Hintertüren für Postfächer – außerhalb der Reichweite einer gestohlenen Genehmigung bleiben. Zwei schreibgeschützte Bereiche werden daneben angefordert, userinfo.email und userinfo.profile: Sie sind die Methode, mit der die Zulassungsliste und die Sitzungsbindung wissen, welcher Account angemeldet ist, und sie greifen nicht auf E-Mails zu.

• Header können nicht geschmuggelt 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 – ein Bcc in einer Betreffzeile beispielsweise. Medientypen werden validiert, und zitierter Verlauf wird HTML-kodiert. Dies überwacht nicht die Argumente selbst: bcc ist ein echter Parameter, sodass ein Modell, das auf eine in einem Nachrichtentext versteckte Anweisung reagiert, dieses dennoch ausfüllen könnte, und die Bestätigungsaufforderung Ihres Clients bleibt die Kontrollinstanz dafür.

• Zugriff kann entzogen werden. Die Einschränkung von ALLOWED_EMAILS stoppt neue Anmeldungen. Der Zugriff eines einzelnen Accounts wird unter myaccount.google.com/connections widerrufen. Das Rotieren des Google-Client-Geheimnisses macht alle Genehmigungen auf einmal ungültig.

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

Wie getestet wurde

253 Unit-Tests decken die Nachrichtenerstellung (MIME-Verschachtelung, RFC 2047-Faltung, RFC 2231-Dateinamen, CR/LF-Ablehnung, Base64-Umbruch), Text-Extraktion über Zeichensätze hinweg, Antwort- und Weiterleitungs-Komposition, die Google-Token-Abläufe, die Anmelde-Zulassungsliste, die CSRF- und Zustandsbindungsprüfungen, die die Browserseite der Anmeldung schützen, sowie die Tools selbst gegen einen Gmail-Ersatz ab – Sitzungsbesitz, Empfänger-Komposition, Anhangsauswahl und was ein teilweise fehlgeschlagener Lesevorgang zurückgibt.

Darüber hinaus wurde jedes Tool gegen echte Gmail-Accounts getestet, wobei ein separater Account überprü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.