Gmail MCP Server

Gmail MCP Server ist ein auf Node.js/TypeScript basierender MCP-stdio-Server, der es OpenClaw ermöglicht, Gmail-E-Mails über das Model Context Protocol zu lesen.

Funktionen

Verwendung der Gmail API OAuth 2.0-Autorisierung mit schreibgeschütztem Zugriffsbereich: https://www.googleapis.com/auth/gmail.readonly
list_emails: Listet E-Mails im Posteingang auf, unterstützt maxResults und Gmail-query-Filter
get_email: Liest Details einer einzelnen E-Mail über die messageId
search_emails: Durchsucht E-Mails mithilfe der Gmail-Suchsyntax
list_labels: Listet alle Gmail-Labels/Ordner auf
Unterstützt den MCP-stdio-Transport zur Verwendung durch OpenClaw

Systemanforderungen

Node.js 18 oder höher
npm
Ein Google-Konto mit Zugriff auf die Gmail API

Installation

npm install
npm run build

Erstellen von OAuth-Anmeldeinformationen in der Google Cloud Console

Öffnen Sie die Google Cloud Console.
Erstellen Sie ein Projekt oder wählen Sie eines aus.
Gehen Sie zu APIs & Services -> Library, suchen Sie nach der Gmail API und aktivieren Sie diese.
Gehen Sie zu APIs & Services -> OAuth consent screen.
Wählen Sie den Benutzertyp. Für den persönlichen Gebrauch wählen Sie normalerweise External.
Geben Sie den Anwendungsnamen, die Support-E-Mail-Adresse des Benutzers und die Kontakt-E-Mail-Adresse des Entwicklers ein.
Fügen Sie im Schritt „Scopes“ die schreibgeschützte Gmail-Berechtigung hinzu: https://www.googleapis.com/auth/gmail.readonly.
Wenn sich die Anwendung im Status „Testing“ befindet, fügen Sie Ihr Gmail-Konto unter „Test users“ hinzu.
Gehen Sie zu APIs & Services -> Credentials.
Klicken Sie auf Create Credentials -> OAuth client ID.
Wählen Sie als Anwendungstyp Desktop app.
Laden Sie nach der Erstellung die JSON-Datei herunter.

Platzieren der credentials.json

Erstellen Sie das Konfigurationsverzeichnis und speichern Sie die heruntergeladene OAuth-JSON-Datei als:

mkdir -p ~/.gmail-mcp
chmod 700 ~/.gmail-mcp
cp /path/to/downloaded/client_secret.json ~/.gmail-mcp/credentials.json
chmod 600 ~/.gmail-mcp/credentials.json

Der endgültige Pfad muss lauten:

~/.gmail-mcp/credentials.json

Ausführen des Autorisierungsprozesses

npm run auth

Das Skript führt folgende Schritte aus:

Startet einen temporären lokalen OAuth-Callback-Dienst
Öffnet den Browser für die Google-Autorisierung
Speichert das Token nach erfolgreicher Autorisierung unter ~/.gmail-mcp/token.json

Falls sich der Browser nicht automatisch öffnet, druckt das Terminal die Autorisierungs-URL aus, die Sie manuell in den Browser kopieren können.

Starten des MCP Servers

npm run start

start verwendet den stdio-Transport und wird normalerweise von OpenClaw als MCP-Server-Unterprozess gestartet; ein manueller Dauerbetrieb ist nicht erforderlich.

Beispiel für die OpenClaw MCP-Konfiguration

Verweisen Sie den Befehl auf den Einstiegspunkt des erstellten Projekts:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/Volumes/DevDisk/symbol/gmailMCP/dist/src/index.js"]
    }
  }
}

Alternativ können Sie das Projekt im Verzeichnis mit npm starten:

{
  "mcpServers": {
    "gmail": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/Volumes/DevDisk/symbol/gmailMCP"
    }
  }
}

Parameterbeschreibung der Tools

list_emails

Listet E-Mails im Posteingang auf.

{
  "maxResults": 10,
  "query": "from:example@gmail.com newer_than:7d"
}

maxResults: Optional, Standard 10, Maximum 50
query: Optional, Gmail-Suchsyntax, beschränkt die Suche auf den Posteingang (INBOX)

get_email

Liest Details einer einzelnen E-Mail.

{
  "messageId": "18f..."
}

Die zurückgegebenen Felder enthalten Absender, Empfänger, Betreff, Datum, Labels, Textkörper, HTML-Körper und Metadaten der Anhänge.

search_emails

Durchsucht Gmail-E-Mails.

{
  "query": "subject:invoice has:attachment newer_than:30d",
  "maxResults": 10
}

query: Erforderlich, unterstützt Gmail-Suchsyntax
maxResults: Optional, Standard 10, Maximum 50

list_labels

Listet alle Labels/Ordner auf.

{}

Dateispeicherorte

OAuth-Anmeldeinformationen: ~/.gmail-mcp/credentials.json
OAuth-Token: ~/.gmail-mcp/token.json
MCP-Server-Einstiegspunkt: dist/src/index.js

Häufig gestellte Fragen

Fehlende Gmail OAuth-Anmeldeinformationen

Stellen Sie sicher, dass die Google OAuth-Client-JSON heruntergeladen und unter folgendem Pfad gespeichert wurde:

~/.gmail-mcp/credentials.json

Fehlendes Gmail OAuth-Token

Führen Sie zuerst Folgendes aus:

npm run auth

access_denied oder Anwendung nicht verifiziert

Wenn sich der OAuth-Zustimmungsbildschirm noch im Status „Testing“ befindet, müssen Sie Ihr aktuelles Gmail-Konto zu den „Test users“ hinzufügen.

invalid_grant

Löschen Sie das alte Token und autorisieren Sie es erneut:

rm ~/.gmail-mcp/token.json
npm run auth

gmail-mcp