Gmail MCP-Server

Ein Model Context Protocol (MCP)-Server, der schreibgeschützten Zugriff auf Gmail bietet. Ermöglicht es Claude Code, sicher in Ihrem Gmail-Posteingang zu suchen, zu lesen und zu analysieren.

Funktionen

• search_emails - Suche unter Verwendung der Gmail-Abfragesyntax

• list_unread - Auflisten ungelesener E-Mails

• get_message - Abrufen des vollständigen Nachrichteninhalts mit Anhangs-Metadaten

• get_thread - Abrufen aller Nachrichten in einem Konversations-Thread

• draft_reply - Vorbereiten des Inhalts einer Antwort (wird NICHT gesendet)

Related MCP server: Gmail MCP Server

Voraussetzungen

• Node.js 18+

• Ein Google Cloud-Projekt mit aktivierter Gmail-API

• OAuth 2.0 Desktop-App-Anmeldedaten

Google Cloud-Einrichtung

1. Google Cloud-Projekt erstellen

1. Gehen Sie zur Google Cloud Console

2. Klicken Sie auf „Projekt auswählen“ → „Neues Projekt“

3. Benennen Sie Ihr Projekt (z. B. „Gmail MCP Server“)

4. Klicken Sie auf „Erstellen“

2. Gmail-API aktivieren

1. Gehen Sie in Ihrem Projekt zu „APIs & Dienste“ → „Bibliothek“

2. Suchen Sie nach „Gmail API“

3. Klicken Sie darauf und drücken Sie „Aktivieren“

3. OAuth-Zustimmungsbildschirm konfigurieren

1. Gehen Sie zu „APIs & Dienste“ → „OAuth-Zustimmungsbildschirm“

2. Wählen Sie „Extern“ (oder „Intern“, falls Sie Google Workspace verwenden)

3. Füllen Sie die erforderlichen Felder aus:

   • App-Name: „Gmail MCP Server“

   • Support-E-Mail für Nutzer: Ihre E-Mail-Adresse

   • Entwickler-Kontakt: Ihre E-Mail-Adresse

4. Klicken Sie auf „Speichern und fortfahren“

5. Bereiche (Scopes) hinzufügen:

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. Fügen Sie Ihre E-Mail-Adresse als Testnutzer hinzu (falls Extern)

7. Schließen Sie die Einrichtung ab

4. OAuth-Anmeldedaten erstellen

1. Gehen Sie zu „APIs & Dienste“ → „Anmeldedaten“

2. Klicken Sie auf „Anmeldedaten erstellen“ → „OAuth-Client-ID“

3. Wählen Sie „Desktop-App“ als Anwendungstyp

4. Benennen Sie sie (z. B. „Gmail MCP Desktop“)

5. Klicken Sie auf „Erstellen“

6. Laden Sie die Client-ID und das Client-Geheimnis herunter oder kopieren Sie diese

Installation

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

Konfiguration

1. Kopieren Sie die Beispiel-Umgebungsdatei:

cp .env.example .env

2. Bearbeiten Sie .env mit Ihren OAuth-Anmeldedaten:

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

Erster Start (Autorisierung)

Beim ersten Start des Servers passiert Folgendes:

1. Ihr Browser wird für die Google-Autorisierung geöffnet

2. Sie werden aufgefordert, sich anzumelden und Berechtigungen zu erteilen

3. Die Token werden lokal in token.json gespeichert

Bei nachfolgenden Starts werden die gespeicherten Token automatisch wiederverwendet.

Verwendung mit Claude Code

Den MCP-Server hinzufügen

claude mcp add gmail node ./dist/index.js

Oder fügen Sie ihn manuell zu Ihrer Claude Code-Konfiguration hinzu:

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

Verfügbare Tools

search_emails

Suchen Sie E-Mails mithilfe der Gmail-Abfragesyntax.

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

Auflisten ungelesener E-Mails (Verknüpfung für die Suche is:unread).

get_message

Abrufen des vollständigen Inhalts einer bestimmten E-Mail anhand der Nachrichten-ID.

get_thread

Abrufen aller Nachrichten in einem Konversations-Thread anhand der Thread-ID.

draft_reply

Vorbereiten eines Antwortentwurfs für einen Thread. Bietet Kontext zum Verfassen einer Antwort, sendet jedoch KEINE E-Mail.

Entwicklung

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

Sicherheitshinweise

• OAuth-Token werden lokal in token.json gespeichert

• Committen Sie niemals .env oder token.json in die Versionsverwaltung

• Der Server fordert nur Lese- und Schreibberechtigungen an

• Es werden keine E-Mails versendet - draft_reply bereitet nur den Inhalt vor

• E-Mail-Inhalte werden nicht protokolliert

Fehlerbehebung

„Missing CLIENT_ID or CLIENT_SECRET“

Stellen Sie sicher, dass Ihre .env-Datei existiert und gültige Anmeldedaten enthält.

„Authorization timeout“

Der OAuth-Vorgang hat ein Zeitlimit von 5 Minuten. Starten Sie den Server neu und schließen Sie die Autorisierung zeitnah ab.

„Token refresh failed“

Löschen Sie token.json und autorisieren Sie sich erneut.

„Access blocked: This app's request is invalid“

Stellen Sie sicher, dass Ihr OAuth-Zustimmungsbildschirm ordnungsgemäß konfiguriert ist und Ihre E-Mail-Adresse als Testnutzer hinzugefügt wurde.