multi-gmail-cowork-mcp

Ein kleiner, selbst gehosteter MCP-Server, der es einem einzigen Claude-Custom-Connector ermöglicht, über mehrere, unabhängig authentifizierte Gmail-Konten zu suchen, zu lesen, zu verfassen und zu senden. Er ist so gebaut, dass er von jedem in ein eigenes Google-Cloud-Projekt gebracht werden kann, ohne gemeinsame Infrastruktur und ohne Codeänderungen pro Bereitstellung.

Claude Cowork
      |
      v
Your private Multi-Gmail MCP  (your own Cloud Run project)
      |
      +-- Gmail account: "personal"
      +-- Gmail account: "work"
      +-- Gmail account: "billing"
      +-- ...more, added any time via the admin page

Fragen Sie Claude zum Beispiel:

• „Durchsuchen Sie mein Arbeits-Gmail nach E-Mails von David.“

• „Suchen Sie in allen verbundenen Gmail-Konten nach ‚invoice 4831‘.“

• „Lesen Sie die neueste E-Mail von ACH Works, ganz egal, auf welchem Konto sie eingegangen ist.“

• „Welches meiner Gmail-Konten hat gestern eine E-Mail von John erhalten?“

Jedes Ergebnis wird ausdrücklich dem Konto-Alias und der E-Mail-Adresse zugeordnet, aus dem bzw. der es stammt. Fragen Sie nach einem Konto ab, das nicht verbunden ist oder dessen Berechtigung abgelaufen ist, erhalten Sie eine eindeutige Fehlermeldung – dieser Server ersetzt niemals stillschweigend ein anderes Konto.

Was dieses Projekt nicht ist

Ausschließlich Gmail. Kein Kalender, kein Drive, keine Docs, keine Sheets und keine Kontato­e. Kein Tool zum dauerhaften Löschen. Kein gemeinsames Backend, kein zentrales Konto, keine Telemetrie.

Related MCP server: Gmail MCP

Datenschutzmodell – wer kann Ihre E-Mail sehen?

Google  <->  Your Google Cloud deployment  <->  Claude / Anthropic

• Sie stellen dies in Ihr eigenes Google-Cloud-Projekt bereit, mit Ihrem eigenen Google-OAuth-Client und Ihrem eigenen Cloud-Run-Dienst.

• Google erstellt bzw. widerruft die OAuth-Berechtigungen; es sieht nur normalen OAuth-Verkehr.

• Ihre Bereitstellung ist der einzige Ort, an dem Gmail-Refresh-Tokens jemals gespeichert werden.

• Claude/Anthropic sieht nur das, was die Tools zurückgeben, wenn Claude sie aufruft (genauso wie bei jedem anderen MCP-Tool) – nichts mehr, und nichts, wenn Sie es nicht nutzen.

• Der Autor dieses Repositories sieht niemals Ihre E-Mails. Es gibt keinen gemeinsamen Server. Ihre Bereitstellung und die Bereitstellung Ihres Cousins haben außer dem Quelltext nichts gemeinsam.

Lesen Sie SECURITY.md für die vollständige Darstellung unserer Vertrauensgrenzen und der Designüberlegungen – einschließlich des genauen Grundes, warum die Authentifizierung genau so implementiert ist, und der bekannten Einschränkungen dieses Projekts. Dieses README wiederholt diese Begründung nicht.

Architektur auf einen Blick

• Sprache/Laufzeit: TypeScript unter Node.js 20+, verifier auf das offizielle @modelcontextprotocol/sdk und Googles google-auth-library.

• Transport: Streamable HTTP (derzeit von MCP empfohlener Remote-Transport), zustandslos – jede Anforderung wird unabhängig verarbeitet, sodass er auf Cloud Run sauber skaliert, ohne eine Session-Affinität.

• Claude ↔ Server-Authentifizierung: MCP-OAuth-2.1-Autorisierungscode-Flow mit PKCE/S256, Dynamic Client Registration, kurzlebigen Zugriffstokens, rotierenden Refresh-Tokens und einem bererungs­lokal lokalen Autorisierungsstatus in Secret Manager.

• Server ↔ Google-Authentifizierung: Standard-OAuth 2.0 mit PKCE, eine Autorisierung pro verbundenem Gmail-Konto, gmail.modify-Scope (Lesen, Verfassen, Senden und Postfachänderung; kein dauerhaftes Löschen).

• Kontospeicher: Ein einziges Secret in Google Secret Manager, das ein kleines JSON-Array im Format (Alias, E-Mail, Refresh-Token) enthält. Kein Daten blanke Datenbank.

Voraussetzungen

• Ein Google-Konto und ein Google-Cloud-Projekt mit aktiver Rechnung (das Build‑Skript gibt die passende Abrechnungsseite aus, wenn das Konto nicht aktiviert ist).

• Ein Claude-Plan, der benutzerdefinierte Connectors unterstützt (für die Verbindung mit Cowork/claude.ai).

• Für die Bereitstellung ist sonst nichts weiter erforderlich: Google Cloud Shell bietet bereits gcloud, curl, openssl und jq.

Kosten und Rechnungsstellung

Cloud Run erfordert ein Projekt mit aktivierter Rechnung. Dieses Deployment ist für die persönliche beziehungsweise Kleingewerbe‑Nutzung ausgelegt: min instances 0 (skaliert bei Inaktivität auf null) und max instances 3. Durch die normale Nutzung – ein paar Suchen, Lesevorgänge und Sendungen pro Tag – bleibt man sicher im Always‑Free Kontingent von Google Cloud für Cloud Run, weshalb die realistische laufende Kosten bei 0 Dollar – ein connects Großaufkommen von Requests über das Gratiskontingte Airline hinaus würde zu gewöhnlichen Cloud‑Run‑Gebühren führen. Das Bootstrap‑Skript gibt optional einen Link für Budget-Benachrichtigungen aus, falls Sie vor jeglicher spending eine Hinweis erhalten möchten.

Ein‑Befehl‑Setup in Cloud Shell (empfohlen)

1. Öffnen Sie dieses Repository über den Button oben in Google Cloud Shell (oder verwenden Sie Open in Cloud Shell auf GitHub).

2. Authentifizieren Sie sich, falls Cloud Shell Sie darum bietet die bittet, und führen Sie dann Folgendes aus:

./scripts/bootstrap.sh

Das Skript fordert Sie auf, ein Projekt auszuwählen (oder erstellt eines), prüft die Abrechnung, aktiviert die erforderlichen APIs, erstellt das fest definierte Cloud‑Run‑Laufzeitdienstkonto, weist nur die benötigten Secret‑Manager Rollen zu, erstellt alle Secrets, installiert Cloud Run und gibt die Prüfungen als PASS/FAIL-Cruches aus. Bei erneutem Führen bleiben vorhandene Secrets, Konten and OAuth-Anmeldedaten und Cloud Run-Diensten fest erhalten.

Das Skript gibt niemals ein Passwort, ein OAuth-Client-Geheimnis, ein Refresh-Token, das Konto‑Store JSON oder lub OAuth-Token der verdauungen MCP-Connections aus. Secrets und Konten werden mit genau definierten Bytes konnte (kein Zeilenumbruch-Fehler der Credentials). Verwenden Sie ./scripts/bootstrap.sh --check für eine reine Vorbereitung Überprüfung der Voraussetzungen in Cloud Shell.

Der eine unvermeidbare Google-Browser-Schritt

Google bietet keine sichere, unterstützte API‑/CLI-Operation an, um einen universellen Web-OAuth-Client General zu vollziehen. Wenn das Bootstrap‑Skript Sie dazu aufruft, öffnen Sie die von ihm ausgewählte Google-Auth-Plattform‑Seite und gehen Sie wie folgtum Sie: vor:

• Konfigurieren Sie die App werden, : Carten Sie die App werden als Extern um den um Hinzuzerten und den ſScope https://..googleapis.com/auth/gmail.modify` hinzuüfuf. Anschließend fügen Sie als Testenutzer die Gmail‑Adresen hinzu, die oaten Sie verden.

• Erzstellen Sie einen OAuth-Client mit dem Anwendungstyp Web application.

• Geben Sie die genua enCallback‑URI en, die das Skript ausgibt: https://.weite-ebner Cloud-Run-Host}/oauth/google/callback.

• Fügen Sie die äergegebenen Client‑ID und das Client‑Secret in die verborgenen Anforder‑ungen in Cloud Shell.

Wenn Google eine Warnserden die App umbestätigetes ist der Warn –false .Wenn betre, werden die angezeigt. Diese ist für persöliche Installaten constante–S rechlzust. Veröffentliche isten den Zustimmungsauf–Schirm under In production ein, falls derfresste Sie die LebeRefresh-Tokens weiterzub–über dem Test-Modus–bjectiven langen hin aus–Schreiben– zu; avesta ‚Produktionszustand`–update swa.. Abüberd as se. Für eine private/kleinere Version ist keine Sh.S. Wenn Speichern.

Am Ende gibt das Bootstrap welche die Admin‑URL die genaute Google-OAuth-Callback-URL, die Produkt-URL und die nächste manuelle Aktion ergibt. Claude authentifiziert sich zum MCPen Endpunkt über die von Claude unterstützte OAuth-Flow mit dem Autoriza–für MCP; in deinem URL ist kein nagelieder Connector‑Header zu bestehen.

Gmail-Konten verbinden

1. Lesen Sie das Admin-Passwort (das alle Cloud Shell-Bootstrap ergibt und nie angezeigt wird) aus, indem Sie den vom Lebens des Bootstrap-Skripts erzeugten Befehl folgendermaßen verwenden:

   gcloud secrets versions access latest --secret=admin-password --project=YOUR_PROJECT_ID

   Öffnen Sie dann die gedruckte Admin‑URL und melden Sie sich mit dem Benutzernamen admin und diesem Passwort an.

2. Geben Sie einen kurzen Alias wie personal oder work ein, klicken Sie auf Add Gmail Account, und vollenden Sie die Google-Autorisierung. Die Autorisierungs-URL verlangt das Abfragen von consent select_account, damit Google jedes Mal die Kontoauswahl zeigt. Die Adresse, die der Callback anzeigt, ist die von Google autorisierte Adresse; sie wird nicht aus dem Alias‑Feld übernommen.

3. Wiederholen Sie dies für so viele Gmail‑Konten wie gewünscht. Jeder Alias ist unabhängig, und alle Ergebnisse werden sowohl dem Alias als auch der bestätigten Gmail‑Adesse zugeordnet.

Claude Cowork verbinden

In Claude öffnen Sie Settings → Connectors → Add custom connector und tragen exakt dies ein:

1. Connector name: Multi Gmail

2. Remote MCP URL: die gedruckte URL, die auf /claude-mcp endet.

3. OAuth Client ID: leeren gelassen (der Server unterstützt Dynamic Client Registration)

4. OAuth Client Secret: leeren gelassen

Die Route /mcp bleibt für bestehende Clients verfügbar; für neue Claude‑Connectors verwenden Sie /claude-mcp, damit die OAuth-Ressourcen-Identität unabhängig von älteren Connector‑Datensätzen wird.

Klicken Sie auf Add, anschließend auf Connect.Klaude erkennt die MCP‑Autorisierungsumgebung, registriert itself self und öffnet die Seite „Authorize MCP" des Bereitstellungs. Melden Sie sich dort mit dem Benutzer **admin** für das admins-Passinort** an** , das in Ihren **civilen** **Secret Manager secret namensenda admin-password–Speichern ist**, und bestätigen tre Sie. Claude wbderdenaftet through sich nach dene Abkenden **Verbindung** via die Callback–URL https://claude.ai/api/mcp/ablaufreg` ... der ree at atures: :..eneur [[, most **„InterestInformation a Speicchnen Sie theisen Sie dem Langatewird. Vonder Gmmail‑OAuth‑Client‑ID or das client —these Werrd von Gmalina nur Googles Gmail‑Betrieb Boden.

Nachdem der Verbindungen verb et list_accounts an zurauf im Auftrag–Columnarisend für jedes –Konto und SEO erklärungenAl tenzieher**(), search_all_accounts überprügAnder NutzüBesezuPossibitte–not um och validate attribution.

Easie Über bere bere** ↩

Verify‑Package::

scripts/acceptance.mjs beweißt, mittler àberemen–vousere Deployment – Konten–Isolation, keine–Fallback bei falschem alias, Entwürfe und senden mit–Zustelung und korrekten From‑Identity. Führt der–full MCP‑OAuth‑Fluss in–einis–echt Remote‑clientes–cit der dGXP5, genbnisse denish–?

MCP_BASE_URL=https://your-service.run.app \
  MCP_ADMIN_PASSWORD='...'   # Secret Manager -> admin-password
  node scripts/acceptance_test.mjs

Die versendet–Generein Les Mail: account-A **→account-B und einen von account-B **→account-A, sodass der Empfänger vonimmer**-**einem Ihnen gehörtes Konto** ist.Reen** Setzen* Sie SKIP_SEND=1`, um das Senden zu überspringen.

Lokale Entwicklung (optional)

Nur für Quellcode‑Entwicklung installieren Sie Node.js 20 ⇄, führen npm install aus, kopieren .env.example nach .env, setzen TOKEN_STORE=file und dran npm run dev. Lokales Gmail‑OAuth erfordert eine eigene OAuth‑Client‑Callback wie http://localhost:8080/oauth/google/callback; do stärken Sie nicht verwandte verantwortliche Produktions-Secrets. Windows‑Nutzer widening für scripts/setup.ps1 und scripts/deploy.ps1 statt des Cloud-Shell-Bootstraps verwenden.

Reautorisieren / Sperren /trennen von Konten

Nach dem Upgrade von der früheren Nur‑Lese‑Version wird jedes bestehende Konto als Erfordert Gmail-Berechtigungsupgrade markiert. Öffnen Sie /admin, klicken Sie für denselben Alias auf Reautorisieren, und schließen Sie danach Googles Zustimmungsbildschirm ab. Der Callback verifiziert, dass Google tatsächlich https://www.googleapis.com/auth/gmail.modify erteilt hat, der erst austerforth das Stock den das Refresh-Token des Alias ersetzt. Bis dahin funktionieren Leseautor Teilers; die Work‑tools geben eine klare Reautorisierungs-Nachricht zurück; nie und nirgends wird ein anderes Alias–Konto herangezogen.

Um Zugriff zu entziehen, klicken Sie neben nebenlesen bei einem Alias auf Disconnect. Das widerruftuelle die Google-Berechtigungen (nach bestem Bemühung Bestand) und entferntBesie das Konto sofort aus dem Credential-Speicher –. Claude bean Sieh if später einen klaren Fehler–Fehler „Nicht verbunden“ beim alias–Ford, niemals einen stillen Fallback.

Um mit demselben Alias nach dem Widerrufen auf Googles Seite wieder zu verbinden, verwenden Sie Verbinden mit demselben Alias. Das Überschreibt das alte Konto nur dann, wenn Google die Authentifizierung erfolgreich abgeschlossen hat.

Schreib-Tools und Sicherheit

Der intern installierten Server bieten create_draft und send_email. Beide erfordern einen ausdrücklich verbundenen Konto-Ali und bilden niemals auf Konto-A fallback. send_email sendet immer mit der verwählten Gmail-Identität; das Resultat enthält die verficifzte Adresse. Die Tools – verwenden – scope gmail.modifyund /mlest– [nicht den breiterenmail.google.com` –Pensionable, ungünstig–, und nicht implement normalem (k) permanent delete. Die Autorisierungsberechtigungen für Claude sollten –nhmeaus** die**.

** –-ungsvollmacht for Auther: . Lesen: unabhängig: ** zu: Zuweisen Sie ** delete: draft**, ** email send ** automatically "** to ** "needs approval"**.

Aktualisierung und Rotation

• Bereitstellungsupdate: Rufen ./scripts/bootstrap.sh nach Änderungen am Quellcode erneut auf, oder um ein net implementede neuen Secret enthalten; die Anweisungen behalten – bestehende Konten, Tokens und OAuth-Client erhalten. Unter Windows scripts/deploy.ps1.

• Admin-Admin: Passwort rotieren: Legen in Secret Manager für die Secret admin-password eine neue Version an und setzen deployed Sie neu. Gültige Claude‑Connector‑Tokens bleiben erhalten (Sie sind nicht vom AdminPasswort abgeleitet); nur zukünftige MCP‑Zustimmungs-Steps verwenden das neue Passwort.

• oauth-state-secret rotieren: Dieses signiert jedes MCP‑OAuth‑Token, ein Rotatet invalidiert daher die vorhandenen Tokend des Claude‑Connectors – verbinden Sie Claude danach neu. Offene Verbindungs‑State‑Tokens für Google‑Konten (10‑Minuten‑Lebensdauer) whereas ablaufen; bereits verbundene Gmail‑Konten sind nicht betroffen.

• Gmail‑Autorisierung rotiren: Verbinden Sie das Alias Passwort erneut über die Admin‑Seite (siehe Reautorisieren / Konten trennen).

Alles löschen

• Gmail-Zugriff entfernen: jedes Konto unter /admin trennen oder den Zugriff direkt unter https://myaccount.google.com/permissions widerrufen.

• Deployment entfernen:

  gcloud run services delete multi-gmail-mcp --region us-central1
  gcloud secrets delete mcp-oauth-state admin-password oauth-state-secret google-client-id google-client-secret gmail-mcp-accounts
  gcloud iam service-accounts delete multi-gmail-mcp-run@YOUR_PROJECT_ID.iam.gserviceaccount.com

• OAuth-Client löschen: Cloud Console -> APIs & Services -> Credentials -> die OAuth-Client-ID löschen und optional die Konfiguration des OAuth-Zustimmungsbildschirms löschen.

• Oder am einfachsten: das gesamte Google-Cloud-Projekt löschen.

Fehlerbehebung

• „Account needs to be reconnected“-Fehler: Der gespeicherte Refresh-Token wurde von Google abgelehnt (widerrufen, abgelaufen oder der Zustimmungsbildschirm steckt in „Testing“ – siehe unten). Verbinden Sie das Konto unter /admin erneut.

• Refresh-Tokens laufen nach ~7 Tagen immer wieder ab: Ihr OAuth-Zustimmungsbildschirm hat noch den Veröffentlichungsstatus „Testing“. Setzen Sie ihn auf „In production“ (siehe Schritt 3) – er kann unverifiziert bleiben, das ist für den privaten Gebrauch in Ordnung.

• Claude kann den Connector nicht erreichen / die Verbindung schlägt still fehl: Stellen Sie sicher, dass die Service-URL über reines HTTPS ohne Weiterleitung zu einem anderen Host aufgelöst wird. Öffnen Sie dann die MCP-URL, die auf /claude-mcp endet, in Claude und klicken Sie erneut auf Verbinden. Der Server muss beim Aufruf ohne Zugriffstoken OAuth-Metadaten und eine 401-Challenge zurückgeben; ein statischer Request-Header ist nicht erforderlich.

• gcloud run deploy schlägt fehl, wenn APIs nicht aktiviert sind: Führen Sie scripts/setup.ps1 erneut aus, oder führen Sie gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com gmail.googleapis.com iam.googleapis.com aus.

• Lokale Entwicklung erreicht Google nicht über HTTPS (Zertifikatfehler): Das ist fast immer ein lokales Problem (ein Unternehmensproxy oder eine Antivirensoftware mit TLS-Interception), kein Fehler in diesem Projekt. Prüfen Sie die vertrauenswürdigen Stammzertifikate Ihres Rechners.

Google OAuth Testing vs. dauerhafte Nutzung

Google-Cloud-OAuth-Clients starten im Veröffentlichungsstatus Testing. Solange sie sich im Testing-Zustand befinden, laufen Refresh-Tokens für sensitive/restricted Scopes (dazu gehört gmail.modify) nach 7 Tagen ab – egal, wie wenige Benutzer Sie haben. Wenn Sie das unverändert lassen, fällt der Connector dadurch wöchentlich stillschweigend aus.

Die Lösung ist nicht die Google-Verifizierung (ein Prozess, der mehrere Monate dauert und für öffentlich genutzte SaaS vorgesehen ist). Es ist einfacher: Klicken Sie auf App veröffentlichen, um den Zustimmungsbildschirm auf In production umzustellen. Für eine App, die nur gmail.modify anfordert und insgesamt unter 100 verbundenen Google-Konten bleibt, behandelt Googles eigene Dokumentation das Pauschal als vollständig unterstützten persönlichen oder kleinskaligen Anwendungsfall – keine Verifizierung erforderlich. Der einzige sichtbare Effekt ist, dass jedes neu verbundene Konto beim Erteilen der Zustimmung einmal die Warnung „Google hat diese App nicht verifiziert“ sehen und durchklicken muss. Diese Warnung ist zu erwarten; sie bedeutet nicht, dass etwas falsch konfiguriert ist. Siehe SECURITY.md für die zugrunde liegenden Regeln und Quellen.

Repository-Struktur

src/            TypeScript source (server, MCP tools, admin/setup UI, OAuth flows)
scripts/        bootstrap.sh (Cloud Shell), setup.ps1/deploy.ps1 (Windows),
                acceptance_test.mjs (verify any deployment end-to-end)
.env.example    Local-dev configuration template (placeholders only)
SECURITY.md     Trust model, design rationale, known limitations

Lizenz

MIT – siehe LICENSE.