MCP Headless Gmail Server

Ein MCP-Server (Model Context Protocol), der das Abrufen und Senden von Gmails ohne lokale Anmeldeinformationen oder Token-Einrichtung ermöglicht.

Warum MCP Headless Gmail Server?

Entscheidende Vorteile

Headless- und Remote-Betrieb : Im Gegensatz zu anderen MCP-Gmail-Lösungen, die außerhalb von Docker ausgeführt werden müssen und lokalen Dateizugriff erfordern, kann dieser Server in Remote-Umgebungen vollständig Headless ohne Browser und ohne lokalen Dateizugriff ausgeführt werden.
Entkoppelte Architektur : Jeder Client kann den OAuth-Flow unabhängig abschließen und dann Anmeldeinformationen als Kontext an diesen MCP-Server übergeben, wodurch eine vollständige Trennung zwischen der Speicherung der Anmeldeinformationen und der Serverimplementierung entsteht.

Nett, aber nicht kritisch

Fokussierte Funktionalität : In vielen Anwendungsfällen, insbesondere bei Marketinganwendungen, wird nur Gmail-Zugriff ohne zusätzliche Google-Dienste wie Kalender benötigt, weshalb diese fokussierte Implementierung ideal ist.
Docker-Ready : Entwickelt mit Blick auf die Containerisierung für eine gut isolierte, umgebungsunabhängige Einrichtung mit einem Klick.
Zuverlässige Abhängigkeiten : Basiert auf der gut gepflegten Bibliothek „Google API Python Client“.

Merkmale

Erhalten Sie die neuesten E-Mails von Gmail mit den ersten 1.000 Zeichen des Textkörpers
Erhalten Sie den vollständigen E-Mail-Textinhalt in 1K-Blöcken mithilfe des Offset-Parameters
Senden Sie E-Mails über Gmail
Zugriffstoken separat aktualisieren
Automatische Handhabung von Aktualisierungstoken

Voraussetzungen

Python 3.10 oder höher
Google API-Anmeldeinformationen (Client-ID, Client-Geheimnis, Zugriffstoken und Aktualisierungstoken)

Installation

# Clone the repository
git clone https://github.com/baryhuang/mcp-headless-gmail.git
cd mcp-headless-gmail

# Install dependencies
pip install -e .

Docker

Erstellen des Docker-Images

# Build the Docker image
docker build -t mcp-headless-gmail .

Verwendung mit Claude Desktop

Sie können Claude Desktop für die Verwendung des Docker-Images konfigurieren, indem Sie Ihrer Claude-Konfiguration Folgendes hinzufügen:

Docker

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "buryhuang/mcp-headless-gmail:latest"
      ]
    }
  }
}

npm-Version

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@peakmojo/mcp-server-headless-gmail"
      ]
    }
  }
}

Hinweis: Bei dieser Konfiguration müssen Sie Ihre Google-API-Anmeldeinformationen in den Tool-Aufrufen angeben, wie im Abschnitt „Verwenden der Tools“ beschrieben. Gmail-Anmeldeinformationen werden nicht als Umgebungsvariablen übergeben, um die Trennung zwischen Anmeldeinformationsspeicher und Serverimplementierung zu gewährleisten.

Plattformübergreifendes Publizieren

Um das Docker-Image für mehrere Plattformen zu veröffentlichen, können Sie den Befehl docker buildx verwenden. Führen Sie dazu die folgenden Schritte aus:

Erstellen Sie eine neue Builder-Instanz (falls noch nicht geschehen):
docker buildx create --use
Erstellen und pushen Sie das Image für mehrere Plattformen :
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t buryhuang/mcp-headless-gmail:latest --push .
Überprüfen Sie, ob das Bild für die angegebenen Plattformen verfügbar ist :
docker buildx imagetools inspect buryhuang/mcp-headless-gmail:latest

Verwendung

Der Server stellt Gmail-Funktionalität über MCP-Tools bereit. Die Authentifizierung wird durch ein spezielles Token-Aktualisierungstool vereinfacht.

Starten des Servers

mcp-server-headless-gmail

Verwenden der Tools

Wenn Sie einen MCP-Client wie Claude verwenden, stehen Ihnen zwei Hauptmethoden zur Authentifizierung zur Verfügung:

Aktualisieren von Token (Erster Schritt oder wenn Token ablaufen)

Wenn Sie sowohl Zugriffs- als auch Aktualisierungstoken haben:

{
  "google_access_token": "your_access_token",
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Wenn Ihr Zugriffstoken abgelaufen ist, können Sie die Aktualisierung nur mit dem Aktualisierungstoken durchführen:

{
  "google_refresh_token": "your_refresh_token",
  "google_client_id": "your_client_id",
  "google_client_secret": "your_client_secret"
}

Dadurch werden ein neues Zugriffstoken und dessen Ablaufzeit zurückgegeben, die Sie für nachfolgende Aufrufe verwenden können.

Aktuelle E-Mails abrufen

Ruft aktuelle E-Mails mit den ersten 1.000 Zeichen jedes E-Mail-Texts ab:

{
  "google_access_token": "your_access_token",
  "max_results": 5,
  "unread_only": false
}

Die Antwort umfasst:

E-Mail-Metadaten (ID, Thread-ID, Von, An, Betreff, Datum usw.)
Die ersten 1000 Zeichen des E-Mail-Textes
body_size_bytes : Gesamtgröße des E-Mail-Textes in Bytes
contains_full_body : Boolescher Wert, der angibt, ob der gesamte Textkörper enthalten (true) oder abgeschnitten (false) ist.

Vollständigen E-Mail-Textinhalt abrufen

Bei E-Mails mit einem Textkörper von mehr als 1.000 Zeichen können Sie den gesamten Inhalt in Blöcken abrufen:

{
  "google_access_token": "your_access_token",
  "message_id": "message_id_from_get_recent_emails",
  "offset": 0
}

Sie können E-Mail-Inhalte auch nach Thread-ID abrufen:

{
  "google_access_token": "your_access_token",
  "thread_id": "thread_id_from_get_recent_emails",
  "offset": 1000
}

Die Antwort umfasst:

Ein 1k-Block des E-Mail-Textes, beginnend ab dem angegebenen Offset
body_size_bytes : Gesamtgröße des E-Mail-Textes
chunk_size : Größe des zurückgegebenen Blocks
contains_full_body : Boolescher Wert, der angibt, ob der Block den Rest des Hauptteils enthält

Um den gesamten E-Mail-Text einer langen Nachricht abzurufen, führen Sie sequenzielle Aufrufe durch und erhöhen Sie den Offset jedes Mal um 1000, bis contains_full_body wahr ist.

Senden einer E-Mail

{
  "google_access_token": "your_access_token",
  "to": "recipient@example.com",
  "subject": "Hello from MCP Gmail",
  "body": "This is a test email sent via MCP Gmail server",
  "html_body": "<p>This is a <strong>test email</strong> sent via MCP Gmail server</p>"
}

Token-Aktualisierungs-Workflow

Beginnen Sie mit dem Aufruf des Tools gmail_refresh_token mit einem der folgenden Befehle:
- Ihre vollständigen Anmeldeinformationen (Zugriffstoken, Aktualisierungstoken, Client-ID und Client-Geheimnis) oder
- Nur Ihr Aktualisierungstoken, Ihre Client-ID und Ihr Client-Geheimnis, wenn das Zugriffstoken abgelaufen ist
Verwenden Sie das zurückgegebene neue Zugriffstoken für nachfolgende API-Aufrufe.
Wenn Sie eine Antwort erhalten, die auf den Ablauf des Tokens hinweist, rufen Sie das Tool gmail_refresh_token erneut auf, um ein neues Token zu erhalten.

Dieser Ansatz vereinfacht die meisten API-Aufrufe, da nicht für jeden Vorgang Client-Anmeldeinformationen erforderlich sind, die Token-Aktualisierung bei Bedarf jedoch weiterhin möglich ist.

Abrufen der Google-API-Anmeldeinformationen

Um die erforderlichen Google-API-Anmeldeinformationen zu erhalten, führen Sie die folgenden Schritte aus:

Gehen Sie zur Google Cloud Console
Erstellen eines neuen Projekts
Aktivieren Sie die Gmail-API
OAuth-Zustimmungsbildschirm konfigurieren
OAuth-Client-ID-Anmeldeinformationen erstellen (als Anwendungstyp „Desktop-App“ auswählen)
Speichern Sie die Client-ID und das Client-Geheimnis
Verwenden Sie OAuth 2.0, um Zugriffs- und Aktualisierungstoken mit den folgenden Bereichen zu erhalten:
- https://www.googleapis.com/auth/gmail.readonly (zum Lesen von E-Mails)
- https://www.googleapis.com/auth/gmail.send (zum Senden von E-Mails)

Token-Aktualisierung

Dieser Server implementiert eine automatische Token-Aktualisierung. Wenn Ihr Zugriffstoken abläuft, verwendet der Google API-Client das Aktualisierungstoken, die Client-ID und das Client-Geheimnis, um ohne Benutzereingriff ein neues Zugriffstoken zu erhalten.

Sicherheitshinweis

Dieser Server benötigt direkten Zugriff auf Ihre Google API-Anmeldeinformationen. Bewahren Sie Ihre Token und Anmeldeinformationen stets sicher auf und geben Sie sie niemals an nicht vertrauenswürdige Dritte weiter.

Lizenz

Weitere Einzelheiten finden Sie in der Datei LICENSE.

MCP Headless Gmail Server

Integrations