gmail-multi-mcp-server

Ein MCP-Server, der Claude mit mehreren Gmail-Konten gleichzeitig verbindet und dieselbe Tool-Oberfl?che w?e der integrierte Gmail-Konnektor bietet. Jedes Tool akzeptiert ein zustzliches account-Argument, das angibt, auf welches Postfach zugegriffen werden soll – das ist der einzige strukturelle Unterschied zum Ein-Postfach-Konnektor.

"Check my work inbox for anything from the lender, and draft the reply from my personal account."

Warum es das gibt

Der integrierte Gmail-Konnektor autorisiert ein Postfach. Wenn du getrennte Konten betreibst – Arbeit, privat, einen Firmenalias – musst du st?ndig wechseln. Dieser Server speichert Anmeldedaten f?r so viele Gmail-Konten, wie du autorisierst, und leitet jeden Aufruf an das von dir genannte weiter.

Related MCP server: multiGmailMCP

Voraussetzungen

• Node.js 20 oder neuer

• Ein Google-Cloud-Projekt mit aktivierter Gmail-API und einem OAuth-Client vom Typ Desktop-App

1. Google-OAuth-Client erstellen

1. Öffne die Google Cloud Console und w?hle ein Projekt aus oder erstelle eines.

2. APIs & Dienste → Bibliothek → aktiviere die Gmail-API.

3. APIs & Dienste → OAuth-Zustimmungsbildschirm → konfiguriere ihn. Solange sich die App im Status Test befindet, füge unter Testnutzer jede Gmail-Adresse hinzu, die du verbinden möchtest.

4. APIs & Dienste → Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID → als Anwendungstyp Desktop-App. Lade die JSON herunter.

Desktop-App-Clients erlauben Loopback-Umleitungen auf jedem beliebigen Port, was der add-account-Ablauf nutzt.

2. Installieren und Erstellen

git clone <this repo>
cd Gmail-MCP
npm install
npm run build

3. Server auf deinen OAuth-Client ausrichten

Wähle eine Option:

# Option A — save the downloaded JSON where the server looks by default
mkdir -p ~/.gmail-mcp && cp ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

# Option B — point at it explicitly
export GMAIL_MCP_CREDENTIALS=/path/to/client_secret.json

# Option C — pass the values directly
export GMAIL_MCP_CLIENT_ID=...apps.googleusercontent.com
export GMAIL_MCP_CLIENT_SECRET=...

4. Jedes Postfach autorisieren

Einmal pro Gmail-Konto ausführen:

node dist/index.js add-account --alias work
node dist/index.js add-account --alias personal
node dist/index.js list-accounts

Jeder Durchlauf gibt eine Google-Zustimmungs-URL aus, wartet auf einem lokalen Loopback-Port auf die Weiterleitung und speichert das resultierende Refresh-Token. Auf einem headless-Rechner füge --manual hinzu und füge die weitergeleitete URL wieder ein.

Konten, die w?hrend des laufenden Servers hinzugefügt werden, werden automatisch ?bernommen – ein Neustart ist nicht erforderlich.

5. Mit Claude verbinden

Claude Code

claude mcp add gmail-multi -- node /absolute/path/to/Gmail-MCP/dist/index.js

Claude Desktop – in claude_desktop_config.json einfügen:

{
  "mcpServers": {
    "gmail-multi": {
      "command": "node",
      "args": ["/absolute/path/to/Gmail-MCP/dist/index.js"],
      "env": {
        "GMAIL_MCP_CREDENTIALS": "/absolute/path/to/client_secret.json"
      }
    }
  }
}

Kontoauswahl

Jedes Tool außer list_accounts akzeptiert account. Die Zuordnung erfolgt in dieser Reihenfolge:

1. die vollständige E-Mail-Adresse – mikael@example.com

2. den beim add-account-Aufruf festgelegten Alias – work

3. den lokalen Teil vor @ – mikael

4. ein beliebiges eindeutiges Pr?fix

account ist optional, wenn nur ein Postfach konfiguriert ist oder wenn GMAIL_MCP_DEFAULT_ACCOUNT gesetzt ist. Andernfalls ist es erforderlich; die Fehlermeldung listet auf, was verfügbar ist.

IDs gelten pro Postfach. Eine Nachrichten-, Thread-, Entwurfs- oder Label-ID aus einem Konto ist in einem anderen bedeutungslos. Eine „not found“-Fehlermeldung bedeutet in der Regel, dass das falsche account übergeben wurde.

Tools

35 Tools – die Tool-Oberfl?che des Konnektors plus zwei für mehrere Konten.

Die Toolnamen entsprechen bewusst denen des Gmail-Konnektors, damit Prompts und Gewohnheiten übernommen werden können. MCP-Clients versehen Tools mit einem Namensraum pro Server, sodass beide gleichzeitig ohne Kollision aktiviert werden können.

Unterschiede zum integrierten Konnektor

Alles unten Genannte ist additiv – nichts, was der Konnektor tut, verhält sich hier anders.

• account bei jedem Tool, zustzlich list_accounts und get_profile.

• response_format (markdown | json) bei jedem Tool. Markdown ist die Standardeinststellung und bleibt kompakt; die vollst?ndige strukturierte Nutzlast wird in jedem Fall als structuredContent zur?ckgegeben.

• delete_draft und get_message_attachment, die der Konnektor referenziert, aber nicht bereitstellt.

• reply akzeptiert quoteOriginal (Standard false), um das Original als zitierten Block anzuhängen.

• forward akzeptiert includeAttachments (Standard true); setze es auf false, um große Dateien auszulassen.

• get_message_attachment akzeptiert savePath, um eine Datei auf die Festplatte zu schreiben, anstatt base64 einzubetten.

• Antworten sind auf 25.000 Zeichen begrenzt; dabei werden zuerst paginierte Listen verkleinert, und es wird genau angegeben, was entfernt wurde und wie der Rest abgerufen werden kann.

Wissenswertes Verhalten

• search_threads gibt eine Vorschau der ältesten Nachrichten jedes Threads zur?ck (~5), wie der Konnektor. Rufe get_thread auf, bevor du etwas ?ber aktuelle oder ungelesene E-Mails beantwortest.

• Entwürfe sind von search_threads ausgeschlossen, sofern die Abfrage Entwürfe erw?hnt. Verwende list_drafts.

• Labels werden über die ID angesprochen, nicht über den Anzeigenamen. Rufe zuerst list_labels auf.

• DRAFT und SENT sind schreibgeschützt; das Hinzufügen von TRASH/SPAM wird an die apply_sensitive_*-Tools weitergeleitet, sodass zerstörerische Aktionen immer explizit benannt werden.

• update_draft führt Felder zusammen, aber Anhänge werden ersetzt, nicht zusammengeführt – die Antwort berichtet, wie viele verworfen wurden.

• reply setzt In-Reply-To und References, damit Clients Threads korrekt zuordnen, und adressiert die Antwort niemals an das autorisierte Postfach selbst.

Sicherheit

• Refresh-Tokens liegen in ~/.gmail-mcp/accounts.json, das atomar mit 0600 in einem 0700-Verzeichnis geschrieben wird. Jeder mit Lesezugriff auf diese Datei hat vollständigen Zugriff auf die Postf?cher.

• Der OAuth-Ablauf validiert den state-Parameter und lauscht nur auf 127.0.0.1.

• remove-account löscht das lokale Token. Um den Zugriff vollständig zu widerrufen, entferne die App außerdem unter myaccount.google.com/permissions.

• Die erteilten Berechtigungen erlauben das Lesen, Senden und Löschen von E-Mails. send_message, reply und forward senden sofort – die Tool-Beschreibungen weisen das Modell an, create_draft zu bevorzugen, wenn der Benutzer nicht eindeutig darum gebeten hat, dass E-Mails versendet werden.

Entwicklung

npm run build         # compile TypeScript to dist/
npm test              # build, then unit tests + stdio smoke test
npm run test:unit     # MIME, reply addressing, parsing, truncation — no network
npm run test:smoke    # boots the server, checks all 35 tools register
npm run inspect       # open the MCP Inspector against the server

src/
  index.ts            CLI entry point and server bootstrap
  constants.ts        scopes, limits, paths
  types.ts            normalized message/thread/draft shapes
  auth/               token store, OAuth flow, account registry
  schemas/common.ts   shared Zod fields (account, formats, pagination, colors)
  services/           Gmail parsing, MIME building, formatting, errors
  tools/              tool registration by domain

Fehlerbehebung

Lizenz

MIT