Gmail AutoAuth MCP-Server
Ein Model Context Protocol (MCP)-Server für die Gmail-Integration in Claude Desktop mit automatischer Authentifizierungsunterstützung. Dieser Server ermöglicht KI-Assistenten die Verwaltung von Gmail durch natürliche Sprachinteraktionen.
Merkmale
- Senden Sie E-Mails mit Betreff, Inhalt, Anhängen und Empfängern
- Unterstützung für HTML-E-Mails und mehrteilige Nachrichten sowohl mit HTML- als auch mit Nur-Text-Versionen
- Vollständige Unterstützung für internationale Zeichen in Betreffzeilen und E-Mail-Inhalten
- Lesen Sie E-Mail-Nachrichten anhand der ID mit erweiterter MIME-Strukturverarbeitung
- Informationen zu E-Mail-Anhängen anzeigen (Dateinamen, Typen, Größen)
- E-Mails anhand verschiedener Kriterien (Betreff, Absender, Datumsbereich) durchsuchen
- Umfassende Etikettenverwaltung mit der Möglichkeit, Etiketten zu erstellen, zu aktualisieren, zu löschen und aufzulisten
- Alle verfügbaren Gmail-Labels auflisten (systemdefiniert und benutzerdefiniert)
- Listen Sie E-Mails im Posteingang, in gesendeten oder benutzerdefinierten Labels auf
- E-Mails als gelesen/ungelesen markieren
- E-Mails in andere Labels/Ordner verschieben
- E-Mails löschen
- Stapelverarbeitung zur effizienten Verarbeitung mehrerer E-Mails gleichzeitig
- Vollständige Integration mit der Gmail-API
- Einfacher OAuth2-Authentifizierungsablauf mit automatischem Browserstart
- Unterstützung für Anmeldeinformationen sowohl für Desktop- als auch für Webanwendungen
- Globale Speicherung von Anmeldeinformationen für mehr Komfort
Installation und Authentifizierung
Installation über Smithery
So installieren Sie Gmail AutoAuth für Claude Desktop automatisch über Smithery :
npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude
Manuelle Installation
- Erstellen Sie ein Google Cloud-Projekt und rufen Sie die Anmeldeinformationen ab:a. Erstellen Sie ein Google Cloud-Projekt:
- Gehen Sie zur Google Cloud Console
- Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes aus
- Aktivieren Sie die Gmail-API für Ihr Projekt
b. OAuth 2.0-Anmeldeinformationen erstellen:
- Gehen Sie zu „APIs & Dienste“ > „Anmeldeinformationen“
- Klicken Sie auf „Anmeldeinformationen erstellen“ > „OAuth-Client-ID“.
- Wählen Sie als Anwendungstyp entweder „Desktop-App“ oder „Webanwendung“
- Geben Sie ihm einen Namen und klicken Sie auf „Erstellen“.
- Für Webanwendungen fügen Sie
http://localhost:3000/oauth2callback zu den autorisierten Umleitungs-URIs hinzu. - Laden Sie die JSON-Datei mit den OAuth-Schlüsseln Ihres Clients herunter
- Benennen Sie die Schlüsseldatei in
gcp-oauth.keys.json um
- Authentifizierung ausführen:Sie können sich auf zwei Arten authentifizieren:a. Globale Authentifizierung (empfohlen):
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/
# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth
- Suchen Sie nach
gcp-oauth.keys.json im aktuellen Verzeichnis oder ~/.gmail-mcp/ - Wenn es im aktuellen Verzeichnis gefunden wird, kopieren Sie es nach
~/.gmail-mcp/ - Öffnen Sie Ihren Standardbrowser für die Google-Authentifizierung
- Anmeldeinformationen speichern als
~/.gmail-mcp/credentials.json
Notiz :
- Nach erfolgreicher Authentifizierung werden die Anmeldeinformationen global in
~/.gmail-mcp/ gespeichert und können von jedem Verzeichnis aus verwendet werden - Die Anmeldeinformationen für Desktop-Apps und Webanwendungen werden unterstützt.
- Stellen Sie für die Anmeldeinformationen von Webanwendungen sicher, dass Sie
http://localhost:3000/oauth2callback zu Ihren autorisierten Umleitungs-URIs hinzufügen.
- In Claude Desktop konfigurieren:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
Docker-Unterstützung
Wenn Sie Docker bevorzugen:
- Authentifizierung:
docker run -i --rm \
--mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
-v mcp-gmail:/gmail-server \
-e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
-e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
-p 3000:3000 \
mcp/gmail auth
- Verwendung:
{
"mcpServers": {
"gmail": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"mcp-gmail:/gmail-server",
"-e",
"GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
"mcp/gmail"
]
}
}
}
Cloud-Server-Authentifizierung
Für Cloud-Serverumgebungen (wie n8n) können Sie während der Authentifizierung eine benutzerdefinierte Rückruf-URL angeben:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
Einrichtungsanweisungen für die Cloud-Umgebung
- Reverse-Proxy konfigurieren:
- Richten Sie Ihren n8n-Container so ein, dass ein Port für die Authentifizierung verfügbar ist
- Konfigurieren Sie einen Reverse-Proxy, um den Verkehr von Ihrer Domäne (z. B.
gmail.gongrzhe.com ) an diesen Port weiterzuleiten
- DNS-Konfiguration:
- Fügen Sie in Ihren DNS-Einstellungen einen A-Eintrag hinzu, um Ihre Domain in die IP-Adresse Ihres Cloud-Servers aufzulösen
- Einrichtung der Google Cloud Platform:
- Fügen Sie in Ihrer Google Cloud Console Ihre benutzerdefinierte Domänen-Callback-URL (z. B.
https://gmail.gongrzhe.com/oauth2callback ) zur Liste der autorisierten Umleitungs-URIs hinzu
- Authentifizierung ausführen:
npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback
- Konfigurieren Sie in Ihrer Anwendung:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}
Dieser Ansatz ermöglicht ordnungsgemäß funktionierende Authentifizierungsabläufe in Umgebungen, in denen der lokale Host nicht zugänglich ist, wie etwa bei containerisierten Anwendungen oder Cloud-Servern.
Der Server bietet die folgenden Tools, die über Claude Desktop verwendet werden können:
1. E-Mail senden ( send_email )
Sendet sofort eine neue E-Mail. Unterstützt Nur-Text, HTML und mehrteilige E-Mails.
{
"to": ["recipient@example.com"],
"subject": "Meeting Tomorrow",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"cc": ["cc@example.com"],
"bcc": ["bcc@example.com"],
"mimeType": "text/plain"
}
HTML-E-Mail-Beispiel:
{
"to": ["recipient@example.com"],
"subject": "Meeting Tomorrow",
"mimeType": "text/html",
"body": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}
Beispiel für eine mehrteilige E-Mail (HTML + einfacher Text):
{
"to": ["recipient@example.com"],
"subject": "Meeting Tomorrow",
"mimeType": "multipart/alternative",
"body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
"htmlBody": "<html><body><h1>Meeting Reminder</h1><p>Just a reminder about our <b>meeting tomorrow</b> at 10 AM.</p><p>Best regards</p></body></html>"
}
2. E-Mail-Entwurf ( draft_email )
Erstellt einen E-Mail-Entwurf, ohne ihn zu senden.
{
"to": ["recipient@example.com"],
"subject": "Draft Report",
"body": "Here's the draft report for your review.",
"cc": ["manager@example.com"]
}
3. E-Mail lesen ( read_email )
Ruft den Inhalt einer bestimmten E-Mail anhand ihrer ID ab.
{
"messageId": "182ab45cd67ef"
}
4. E-Mails suchen ( search_emails )
Sucht nach E-Mails mit der Gmail-Suchsyntax.
{
"query": "from:sender@example.com after:2024/01/01 has:attachment",
"maxResults": 10
}
5. E-Mail ändern ( modify_email )
Fügt Beschriftungen zu E-Mails hinzu oder entfernt sie (in andere Ordner verschieben, archivieren usw.).
{
"messageId": "182ab45cd67ef",
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"]
}
6. E-Mail löschen ( delete_email )
Löscht eine E-Mail dauerhaft.
{
"messageId": "182ab45cd67ef"
}
7. E-Mail-Labels auflisten ( list_email_labels )
Ruft alle verfügbaren Gmail-Labels ab.
8. Label erstellen ( create_label )
Erstellt ein neues Gmail-Label.
{
"name": "Important Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
9. Label aktualisieren ( update_label )
Aktualisiert ein vorhandenes Gmail-Label.
{
"id": "Label_1234567890",
"name": "Urgent Projects",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
10. Label löschen ( delete_label )
Löscht ein Gmail-Label.
{
"id": "Label_1234567890"
}
11. Label abrufen oder erstellen ( get_or_create_label )
Ruft ein vorhandenes Label nach Namen ab oder erstellt es, wenn es nicht vorhanden ist.
{
"name": "Project XYZ",
"messageListVisibility": "show",
"labelListVisibility": "labelShow"
}
12. E-Mails stapelweise ändern ( batch_modify_emails )
Ändert Beschriftungen für mehrere E-Mails in effizienten Stapeln.
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"addLabelIds": ["IMPORTANT"],
"removeLabelIds": ["INBOX"],
"batchSize": 50
}
13. E-Mails stapelweise löschen ( batch_delete_emails )
Löscht mehrere E-Mails dauerhaft in effizienten Stapeln.
{
"messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
"batchSize": 50
}
Erweiterte Suchsyntax
Das Tool search_emails unterstützt die leistungsstarken Suchoperatoren von Gmail:
| Operator | Beispiel | Beschreibung |
|---|
from: | from:john@example.com | E-Mails von einem bestimmten Absender |
to: | to:mary@example.com | An einen bestimmten Empfänger gesendete E-Mails |
subject: | subject:"meeting notes" | E-Mails mit spezifischem Text im Betreff |
has:attachment | has:attachment | E-Mails mit Anhängen |
after: | after:2024/01/01 | Nach einem bestimmten Datum empfangene E-Mails |
before: | before:2024/02/01 | Vor einem Datum empfangene E-Mails |
is: | is:unread | E-Mails mit einem bestimmten Status |
label: | label:work | E-Mails mit einem bestimmten Label |
Sie können mehrere Operatoren kombinieren: from:john@example.com after:2024/01/01 has:attachment
Erweiterte Funktionen
Der Server extrahiert E-Mail-Inhalte auf intelligente Weise aus komplexen MIME-Strukturen:
- Priorisiert Klartextinhalte, sofern verfügbar
- Fällt auf HTML-Inhalte zurück, wenn kein einfacher Text verfügbar ist
- Verarbeitet mehrteilige MIME-Nachrichten mit verschachtelten Teilen
- Verarbeitet Informationen zu Anhängen (Dateiname, Typ, Größe)
- Behält die ursprünglichen E-Mail-Header bei (Von, An, Betreff, Datum)
Internationaler Charakter-Support
Der Server unterstützt vollständig Nicht-ASCII-Zeichen in E-Mail-Betreffzeilen und -Inhalten, einschließlich:
- Türkische, chinesische, japanische, koreanische und andere nicht-lateinische Alphabete
- Sonderzeichen und Symbole
- Die richtige Kodierung gewährleistet die korrekte Anzeige in E-Mail-Clients
Umfassendes Etikettenmanagement
Der Server bietet einen vollständigen Satz von Tools zum Verwalten von Gmail-Labels:
- Etiketten erstellen : Erstellen Sie neue Etiketten mit anpassbaren Sichtbarkeitseinstellungen
- Beschriftungen aktualisieren : Benennen Sie Beschriftungen um oder ändern Sie ihre Sichtbarkeitseinstellungen
- Beschriftungen löschen : Vom Benutzer erstellte Beschriftungen entfernen (Systembeschriftungen sind geschützt)
- Suchen oder Erstellen : Holen Sie sich ein Etikett nach Namen oder erstellen Sie es automatisch, wenn es nicht gefunden wird
- Alle Labels auflisten : Alle System- und Benutzerlabels mit detaillierten Informationen anzeigen
- Optionen für die Beschriftungssichtbarkeit : Steuern Sie, wie Beschriftungen in Nachrichten- und Beschriftungslisten angezeigt werden
Zu den Einstellungen für die Beschriftungssichtbarkeit gehören:
messageListVisibility : Steuert, ob das Label in der Nachrichtenliste angezeigt wird ( show oder hide ).labelListVisibility : Steuert, wie das Label in der Labelliste angezeigt wird ( labelShow , labelShowIfUnread oder labelHide )
Diese Funktionen zur Etikettenverwaltung ermöglichen eine anspruchsvolle Organisation von E-Mails direkt über Claude, ohne dass Sie zur Gmail-Oberfläche wechseln müssen.
Batch-Operationen
Der Server verfügt über effiziente Stapelverarbeitungsfunktionen:
- Verarbeiten Sie bis zu 50 E-Mails gleichzeitig (konfigurierbare Stapelgröße)
- Automatische Aufteilung großer E-Mail-Gruppen zur Vermeidung von API-Beschränkungen
- Detaillierte Erfolgs-/Fehlerberichte für jeden Vorgang
- Sanfte Fehlerbehandlung mit individuellen Wiederholungsversuchen
- Perfekt für die Massenverwaltung und Organisation von Posteingängen
Sicherheitshinweise
- OAuth-Anmeldeinformationen werden sicher in Ihrer lokalen Umgebung gespeichert (
~/.gmail-mcp/ ) - Der Server verwendet den Offline-Zugriff, um eine dauerhafte Authentifizierung aufrechtzuerhalten
- Geben Sie Ihre Anmeldeinformationen niemals an die Versionskontrolle weiter und übergeben Sie sie nicht
- Überprüfen und widerrufen Sie regelmäßig ungenutzte Zugriffe in Ihren Google-Kontoeinstellungen.
- Anmeldeinformationen werden global gespeichert, sind aber nur für den aktuellen Benutzer zugänglich
Fehlerbehebung
- OAuth-Schlüssel nicht gefunden
- Stellen Sie sicher, dass sich
gcp-oauth.keys.json entweder in Ihrem aktuellen Verzeichnis oder in ~/.gmail-mcp/ befindet. - Überprüfen Sie die Dateiberechtigungen
- Ungültiges Anmeldeinformationsformat
- Stellen Sie sicher, dass Ihre OAuth-Schlüsseldatei entweder
web oder installed Anmeldeinformationen enthält - Überprüfen Sie bei Webanwendungen, ob die Umleitungs-URI richtig konfiguriert ist
- Port wird bereits verwendet
- Wenn Port 3000 bereits verwendet wird, geben Sie ihn bitte frei, bevor Sie die Authentifizierung ausführen
- Sie können den Prozess über diesen Port finden und stoppen
- Fehler bei Batchvorgängen
- Wenn Batch-Operationen fehlschlagen, werden einzelne Elemente automatisch erneut versucht
- Überprüfen Sie die detaillierten Fehlermeldungen auf bestimmte Fehler
- Erwägen Sie eine Reduzierung der Batchgröße, wenn Sie auf eine Ratenbegrenzung stoßen.
Beitragen
Beiträge sind willkommen! Senden Sie gerne einen Pull Request.
Ausführen von Evaluierungen
Das Evals-Paket lädt einen MCP-Client, der anschließend die Datei index.ts ausführt, sodass zwischen den Tests kein Neuaufbau erforderlich ist. Sie können Umgebungsvariablen laden, indem Sie dem Befehl npx voranstellen. Die vollständige Dokumentation finden Sie hier .
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts
Lizenz
MIT
Unterstützung
Wenn Sie auf Probleme stoßen oder Fragen haben, melden Sie bitte ein Problem im GitHub-Repository.