Gmail MCP Server

Dieses Projekt implementiert einen Model Context Protocol (MCP) Server, der die Interaktion mit Gmail-Konten über IMAP und SMTP ermöglicht. Es bietet Werkzeuge zum Durchsuchen von E-Mails, Abrufen von Inhalten, Verwalten von Labels (Erstellen, Löschen, Umbenennen, Anwenden, Entfernen) sowie zum Senden und Weiterleiten von E-Mails.

Funktionen

• E-Mail-Suche: Durchsuchen Sie E-Mails nach Datumsbereich, Stichwort oder roher Gmail-Abfragezeichenfolge. Unterstützt die Suche in bestimmten Ordnern (Posteingang, Gesendet) und die Begrenzung der Ergebnisse. Verwendet die X-GM-RAW-Erweiterung von Gmail für effiziente Posteingangssuche (z. B. Filtern nach category:primary).

• E-Mail-Inhalt abrufen: Rufen Sie den vollständigen Inhalt (Kopfzeilen, Textkörper, Anhänge) einer bestimmten E-Mail anhand ihrer Sequenz-ID ab.

• Label-Verwaltung (CRUD):

  • Alle verfügbaren Gmail-Labels (Ordner) auflisten.

  • Neue benutzerdefinierte Labels erstellen.

  • Vorhandene benutzerdefinierte Labels umbenennen.

  • Vorhandene benutzerdefinierte Labels löschen (Systemlabels können nicht gelöscht werden).

  • Labels auf einzelne E-Mails anwenden.

  • Labels von einzelnen E-Mails entfernen.

• Stapeloperationen:

  • Labels gleichzeitig auf mehrere E-Mails anwenden (mithilfe von Sequenz-IDs).

  • Labels gleichzeitig von mehreren E-Mails entfernen (mithilfe von Sequenz-IDs).

  • Mehrere E-Mails in ein bestimmtes Label/einen bestimmten Ordner verschieben.

• E-Mail senden: Neue E-Mails senden (erfordert SMTP-Konfiguration).

• E-Mail weiterleiten: Vorhandene E-Mails inklusive Anhängen weiterleiten (erfordert SMTP-Konfiguration).

• Tägliche E-Mail-Anzahl: Anzahl der pro Tag innerhalb eines bestimmten Datumsbereichs empfangenen E-Mails zählen.

Related MCP server: Gmail MCP Server

Projektstruktur

.
├── .gitignore         # Specifies intentionally untracked files that Git should ignore
├── .python-version    # Specifies Python version (used by pyenv)
├── LICENSE            # Project license file
├── pyproject.toml     # Python project configuration (dependencies, build system)
├── README.md          # This file
├── task_list.md       # Tracks development progress
├── uv.lock            # Lock file for uv package manager
├── src/
│   └── email_client/
│       ├── __init__.py
│       ├── config.py        # Handles loading configuration from environment variables (.env)
│       ├── handlers.py      # Implements the logic for handling MCP tool calls
│       ├── imap_client.py   # Contains functions for interacting with IMAP server
│       ├── server.py        # Main MCP server script using @modelcontextprotocol/sdk
│       ├── smtp_client.py   # Contains functions for interacting with SMTP server
│       ├── tool_definitions.py # Defines the available MCP tools and their schemas
│       └── utils.py         # Utility functions (e.g., email parsing, date formatting)
└── ... (other potential files like test scripts, helper scripts)

Einrichtung

1. Repository klonen (falls zutreffend):

   git clone https://github.com/david-strejc/gmail-mcp-server.git
   cd gmail-mcp-server

2. Abhängigkeiten installieren: Dieses Projekt verwendet uv für die Paketverwaltung.

   # Ensure uv is installed (e.g., pip install uv)
   uv venv  # Create virtual environment (.venv)
   uv sync  # Install dependencies from pyproject.toml and uv.lock
   source .venv/bin/activate # Activate the virtual environment

   (Falls Sie uv nicht verwenden, erstellen Sie eine virtuelle Umgebung und installieren Sie die Abhängigkeiten mit pip install -r requirements.txt, sofern eine requirements.txt erstellt wird).

3. Umgebungsvariablen konfigurieren: Erstellen Sie eine .env-Datei im Projektstammverzeichnis und fügen Sie Ihre Gmail-Anmeldedaten und Servereinstellungen hinzu:

   # .env file
   GMAIL_EMAIL=your_email@gmail.com
   GMAIL_PASSWORD=your_app_password # Use an App Password if 2FA is enabled
   GMAIL_IMAP_SERVER=imap.gmail.com
   GMAIL_SMTP_SERVER=smtp.gmail.com
   GMAIL_SMTP_PORT=587 # Or 465 for SSL

   • Wichtig: Für Gmail müssen Sie bei aktivierter Zwei-Faktor-Authentifizierung unbedingt ein "App-Passwort" generieren und verwenden. Standardkennwörter funktionieren nicht. Siehe Googles Dokumentation zu App-Passwörtern.

   • Stellen Sie sicher, dass "Weniger sichere App-Zugriffe" aktiviert ist, falls Sie keine Zwei-Faktor-Authentifizierung verwenden (dies wird jedoch generell nicht empfohlen).

Ausführen des MCP-Servers

Aktivieren Sie die virtuelle Umgebung und führen Sie das Serverskript aus:

source .venv/bin/activate
python src/email_client/server.py

Der Server startet und lauscht auf MCP-Anfragen über Standardeingabe/-ausgabe.

Integration mit einem MCP-Client (z. B. Cline)

Fügen Sie die Serverkonfiguration zur Einstellungsdatei Ihres MCP-Clients hinzu (z. B. cline_mcp_settings.json oder claude_desktop_config.json).

Beispieleintrag für cline_mcp_settings.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/your/project/gmail-mcp-server/.venv/bin/python",
      "args": ["/path/to/your/project/gmail-mcp-server/src/email_client/server.py"],
      "env": {}, // Environment variables are loaded from .env by the script
      "enabled": true, // Set to true to enable
      "autoApprove": [] // Configure auto-approval if desired
    }
    // ... other servers
  }
}

• Ersetzen Sie /path/to/your/project/gmail-mcp-server durch den tatsächlichen absoluten Pfad zu diesem Projektverzeichnis.

• Stellen Sie sicher, dass der command auf die Python-Datei in der virtuellen Umgebung des Projekts verweist (.venv/bin/python).

Sobald die Konfiguration abgeschlossen und der Client aktiviert ist, verbindet sich der Client mit dem Server und die definierten Werkzeuge werden verfügbar.

Verfügbare Werkzeuge (Zusammenfassung)

• search-emails: E-Mails durchsuchen.

• get-email-content: Vollständige E-Mail-Details abrufen.

• count-daily-emails: Tägliche E-Mail-Anzahl zählen.

• list-labels: Alle Labels/Ordner auflisten.

• create-label: Ein neues Label erstellen.

• rename-label: Ein vorhandenes Label umbenennen.

• delete-label: Ein Label löschen.

• apply-label: Ein Label auf eine E-Mail anwenden.

• remove-label: Ein Label von einer E-Mail entfernen.

• apply-label-batch: Ein Label auf mehrere E-Mails anwenden.

• remove-label-batch: Ein Label von mehreren E-Mails entfernen.

• move-email: Eine einzelne E-Mail in ein Label verschieben.

• move-email-batch: Mehrere E-Mails in ein Label verschieben.

• send-email: Eine neue E-Mail senden.

• forward-email: Eine vorhandene E-Mail weiterleiten.

Detaillierte Eingabeschemata für jedes Werkzeug finden Sie in src/email_client/tool_definitions.py.