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

Related MCP server: Systemprompt MCP Gmail Server

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:

1. Erstellen Sie eine neue Builder-Instanz (falls noch nicht geschehen):

   docker buildx create --use

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

3. Ü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

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

2. Verwenden Sie das zurückgegebene neue Zugriffstoken für nachfolgende API-Aufrufe.

3. 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:

1. Gehen Sie zur Google Cloud Console

2. Erstellen eines neuen Projekts

3. Aktivieren Sie die Gmail-API

4. OAuth-Zustimmungsbildschirm konfigurieren

5. OAuth-Client-ID-Anmeldeinformationen erstellen (als Anwendungstyp „Desktop-App“ auswählen)

6. Speichern Sie die Client-ID und das Client-Geheimnis

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