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, mit zitiertem Verlauf senden und allen antworten, 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 für Claude Code auf einem Laptop, claude.ai im Browser und Claude auf dem Handy antwortet. Jede Verbindung meldet sich bei einem Google-Konto an, und das Google-Refresh-Token bleibt in deinem Cloudflare-Konto.

Zwei Dinge treiben Menschen hierher. Die in Claude und Google eingebauten Gmail-Connectors lesen E-Mails und schreiben Entwürfe, können aber nicht senden und binden ein Google-Konto an jedes Assistentenkonto. Server, die senden können, sind meist lokale Prozesse – gut am Schreibtisch, vom Handy aus unsichtbar.

Vergleich

google_workspace_mcp ist das umfangreichste Projekt hier. Es deckt ganz Workspace ab statt nur Gmail, es fügt deine Gmail-Signatur hinzu 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 geschieht.

Zwei Designunterschiede entscheiden über den Rest. Konten über ein Aufrufargument zu routen, erlaubt einer Berechtigung, jedes verbundene Postfach zu erreichen, 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 Anhang-Blobs speichert, kommen mit leerem Textkörper zurück.

Related MCP server: Gmail MCP Connector

Bereitstellen

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

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

• OAuth-Zustimmungsbildschirm → Extern, dann unter Zielgruppe App veröffentlichen drücken. Im Testmodus lässt Google jedes Refresh-Token nach 7 Tagen ablaufen und jede Verbindung stirbt mit ihrem Token. Veröffentlicht zeigt die App beim Anmelden eine Warnung über eine nicht verifizierte 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 Geheimnis 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 Geheimnissen. Er stellt auf workers.dev bereit; eine eigene Domain wird anschließend unter Einstellungen → Domains & Routes 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 neu, nimmt Client-ID und Geheimnis entgegen, generiert einen Cookie-Schlüssel und stellt bereit. Die ersten beiden Antworten landen in wrangler.local.jsonc, das git ignoriert – 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

Die Felder für Client-ID und Geheimnis 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 derselben 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 der Originalnachricht, entfernt 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: Er 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 ihm ü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 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 Hinweis zurück, der das sagt, statt 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 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 trägt weit mehr, als ein Worker ausliefern sollte, daher leben Nachrichtenaufbau, MIME-Parsing und Token-Refresh stattdessen in src/gmail.ts und src/utils.ts.

Endpunkte

Wer sich anmelden kann

ALLOWED_STRANGER 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, sodass das Erweitern dieser Liste niemals den Zugriff auf bereits verbundene Postfächer erweitert. * 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 festgelegt:

Im Workers-Free-Plan 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 darunter; darüber kommen die Überschüsse als Fehler pro Nachricht zurück statt als Ergebnisse. Der kostenpflichtige Plan erlaubt 1000.

Erhöhen Sie einen davon und stellen Sie erneut bereit. Der Ratenbegrenzer von Cloudflare liest seine Obergrenze zur Build-Zeit aus der Binding, daher ist der simple.limit auf jeder Binding der einzige Ort, der sie ändert. Eine Einzelbenutzer-Bereitstellung kann beide unangetastet lassen — die normale Assistentennutzung liegt weit darunter.

Sicherheit

Self-Hosting verschiebt die Vertrauensfrage, anstatt sie zu lösen — hier ist also alles zu finden.

• Ihre Token bleiben Ihre eigenen. Refresh-Tokens sind innerhalb ihres OAuth-Grants in Ihrem KV-Namespace verschlüsselt. Das Durable Object einer Session hält das eine Stunde gültige Access-Token, und das MCP-Agent-Framework behält dort eine Kopie des Grants, solange das Objekt lebt, einschließlich Refresh-Token. Beide Speicherorte liegen in Ihrem eigenen Cloudflare-Konto, im Ruhezustand verschlüsselt. E-Mail wird nie gespeichert — sie wird durchgereicht.

• Eine Session, ein Postfach. Die MCP-Session ist an das Konto gebunden, das sie geöffnet hat, sodass ein Grant für ein Postfach nicht über eine entliehene Session-ID auf ein anderes einwirken kann.

• Scope-Minimalismus. gmail.modify umfasst Lesen, Senden, Labels und Papierkorb. Es schließt dauerhaftes Löschen und den gesamten Bereich gmail.settings.* aus und hält automatische Weiterleitungsregeln und Filter-Exfiltration — die klassischen Postfach-Hintertüren — außerhalb dessen, was ein gestohlener Grant tun könnte. Daneben werden zwei schreibgeschützte Scopes angefordert, userinfo.email und userinfo.profile: Über sie wissen die Allowlist und die Session-Bindung, welches Konto sich angemeldet hat, und sie erreichen keine E-Mails.

• Header können nicht eingeschleust 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 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, ihn trotzdem ausfüllen könnte, und die Genehmigungsaufforderung 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 entzogen. Das Rotieren des Google-Client-Secrets entwertet alle Grants auf einmal.

Der Worker entschlüsselt E-Mail während der Bearbeitung einer Anfrage im Arbeitsspeicher, wie es jeder gehostete Relay tun muss. Falls das für ein bestimmtes Postfach nicht akzeptabel ist, führen Sie für dieses einen lokalen MCP-Server aus.

So wurde getestet

253 Unit-Tests decken die Nachrichtenerstellung ab (MIME-Verschachtelung, RFC-2047-Umbruch, RFC-2231-Dateinamen, CR/LF-Ablehnung, Base64-Umbruch), die Textextraktion über Zeichensätze hinweg, die Zusammenstellung von Antworten und Weiterleitungen, die Google-Token-Flows, die Anmelde-Allowlist, die CSRF- und State-Binding-Prüfungen, die die Browserseite der Anmeldung absichern, sowie die Tools selbst gegen einen Gmail-Stellvertreter — Session-Eigentum, Empfängerzusammenstellung, Anhangsauswahl und die Rückgabe bei teilweise fehlgeschlagenen Lesevorgängen.

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 Bugs

Ö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.