gmail-mcp v1.0.0

Einheitlicher Multi-Account-Google-OAuth2-MCP-Server für Gmail. Durchsuchen, lesen, verfassen, senden, entwerfen und organisieren Sie E-Mails nahtlos über mehrere Google-Konten hinweg.

Funktionen (4 vereinheitlichte Tools)

• gmail_search: Durchsuchen Sie E-Mails mit der offiziellen Gmail-Such-Syntax (is:unread, from:boss@corp.com, subject:invoice, newer_than:2d, has:attachment)

• gmail_read: Lesen Sie den vollständigen E-Mail-Inhalt und die Metadaten (Betreff, Absender, Textkörper, HTML, CC, BCC, Labels, Anhangsliste)

• gmail_send: Senden Sie E-Mails oder erstellen Sie Entwürfe (unterstützt HTML, CC, BCC, Thread-Antworten und Dateianhänge)

• gmail_manage: Beschriften, Archivieren, Papierkorb-Verwaltung, Gelesen/Ungelesen-Umschalter, dauerhaftes Löschen und Multi-Account-Übersicht

Related MCP server: Moist

Multi-Account-Architektur

Ein einzelner Google-Cloud-OAuth-Client (credentials.json) kann mehrere Gmail-Konten authentifizieren. Tokens werden pro Konto in ~/.secrets/gmail/tokens/<account_name>.json gespeichert.

1. Google-OAuth-Anmeldedaten einrichten (einmalig)

1. Erstellen Sie ein Projekt in der Google Cloud Console.

2. Aktivieren Sie die Gmail API.

3. Erstellen Sie eine OAuth-2.0-Client-ID (Desktop-Anwendung).

4. Laden Sie die JSON-Datei mit dem Client-Secret herunter und speichern Sie sie als ~/.secrets/gmail/credentials.json (oder setzen Sie GMAIL_CREDENTIALS_JSON).

2. Konten authentifizieren

Führen Sie die interaktive Autorisierungs-CLI für jedes Konto aus:

gmail-auth default    # Authenticates primary account
gmail-auth work       # Authenticates secondary work account
gmail-auth client_x   # Authenticates any additional account

Alle authentifizierten Konten auflisten:

gmail-auth --list

Installation in MCP-Clients (Claude Desktop, OpenCode, Cursor, Windsurf)

Option 1: Sofort per uvx (empfohlen)

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/gmail-mcp.git", "gmail-mcp"]
    }
  }
}

Option 2: Per pip install

pip install git+https://github.com/Steph-ux/gmail-mcp.git

Dann in Ihrer MCP-Konfiguration:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}

Option 3: Lokaler Klon (Entwicklung)

{
  "mcpServers": {
    "gmail": {
      "command": "python",
      "args": ["D:\\Steph\\script\\gmail-mcp\\server.py"]
    }
  }
}

Anwendungsbeispiele

1. Nachrichten durchsuchen

# Search in default account:
gmail_search(query='is:unread from:github')

# Search in work account:
gmail_search(account='work', query='subject:invoice newer_than:7d')

2. Nachricht lesen

gmail_read(account='work', message_id='18f2a9b4c10d')

3. E-Mail senden oder Entwurf erstellen

# Send direct email:
gmail_send(
    account='default',
    to='colleague@example.com',
    subject='Project Update',
    body_text='Here is the latest status...',
    body_html='<h1>Project Update</h1><p>Here is the latest status...</p>'
)

# Create a draft:
gmail_send(
    account='work',
    to='client@example.com',
    subject='Proposal draft',
    body_text='Please review the proposal.',
    draft=True
)

4. Organisieren & Verwalten

# Archive email:
gmail_manage(account='work', action='archive', message_id='18f2a9b4c10d')

# Mark as unread:
gmail_manage(account='default', action='mark_unread', message_id='18f2a9b4c10d')

# Move to trash:
gmail_manage(account='default', action='trash', message_id='18f2a9b4c10d')

# List active accounts:
gmail_manage(action='list_accounts')

Testen

pytest tests

Lizenz

MIT