mariana-google-mcp

Ein benutzerdefinierter MCP-Server (Model Context Protocol), der Claude Code Zugriff auf Gmail, Google Kalender und Google Kontakte gewährt – mit sicherheitsorientierten Standardeinstellungen.

Design-Philosophie

Dieser Server wurde für Anwender entwickelt, die möchten, dass KI bei der Verwaltung ihres Google-Workspaces hilft, ohne das Risiko versehentlicher Schäden:

Kein E-Mail-Versand. Sie können Entwürfe erstellen, aber das Senden erfordert eine manuelle Aktion in Gmail.
Kein Löschen von Inhalten. Gmail verwendet ein Label "To Be Deleted" (Soft-Delete). Der Kalender stellt Veranstaltungstiteln "DELETE - " voran. Sie überprüfen und bestätigen dies in der Google-Benutzeroberfläche.
Jede Änderung wird protokolliert. Ein reines Append-JSONL-Aktionsprotokoll zeichnet jeden Schreibvorgang mit Zeitstempeln, Tool-Namen, Konto und Zusammenfassung auf.
Multi-Account-Unterstützung. Verwalten Sie persönliche und geschäftliche Konten mit benannten Aliasen.

Einrichtung

1. Google Cloud-Projekt

Gehen Sie zur Google Cloud Console
Erstellen Sie ein neues Projekt (oder verwenden Sie ein bestehendes)
Aktivieren Sie diese APIs:
- Gmail API
- Google Calendar API
- People API (für Kontakte)
Erstellen Sie OAuth 2.0-Anmeldedaten:
- Anwendungstyp: Desktop-App
- Laden Sie die Client-ID und das Client-Geheimnis herunter

2. Installieren und Erstellen

git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build

3. Zu Claude Code hinzufügen

Fügen Sie dies in Ihrer ~/.claude.json unter mcpServers hinzu:

{
  "mcpServers": {
    "mariana-google-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mariana-google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Ersetzen Sie /path/to/ durch den tatsächlichen Pfad zu Ihrem Klon und geben Sie Ihre OAuth-Anmeldedaten ein.

4. Authentifizieren

Führen Sie nach dem Neustart von Claude Code das Tool google_auth aus. Es öffnet ein Browserfenster für die OAuth-Zustimmung. Sobald die Autorisierung erfolgt ist, wird Ihr Token lokal gespeichert und automatisch aktualisiert.

Verfügbare Tools (19)

Authentifizierung & Status

Tool	Beschreibung
`google_auth`	Authentifizierung eines Google-Kontos über den OAuth-Browser-Flow
`google_status`	Überprüfung des Verbindungsstatus für alle konfigurierten Konten

Gmail (9 Tools)

Tool	Beschreibung
`gmail_search`	Suche nach Nachrichten mit der Gmail-Suchsyntax
`gmail_read`	Lesen einer bestimmten Nachricht nach ID (vollständiger Inhalt)
`gmail_list_labels`	Auflisten aller Gmail-Labels/Ordner
`gmail_draft`	Erstellen eines E-Mail-Entwurfs (wird NICHT gesendet)
`gmail_create_label`	Erstellen eines neuen Labels (unterstützt Verschachtelung mit `/`)
`gmail_apply_label`	Anwenden eines Labels auf eine oder mehrere Nachrichten
`gmail_remove_label`	Entfernen eines Labels von einer oder mehreren Nachrichten
`gmail_create_filter`	Erstellen einer Filterregel (Übereinstimmungskriterien → Aktionen)
`gmail_move_to_delete`	Soft-Delete: Verschieben von Nachrichten in ein "To Be Deleted"-Label

Kalender (6 Tools)

Tool	Beschreibung
`calendar_list`	Auflisten anstehender Kalenderereignisse
`calendar_search`	Suche nach Ereignissen nach Stichwort
`calendar_get`	Abrufen vollständiger Details eines bestimmten Ereignisses
`calendar_create`	Erstellen eines Ereignisses (sendet standardmäßig KEINE Einladungen)
`calendar_update`	Ändern eines bestehenden Ereignisses (benachrichtigt standardmäßig KEINE Teilnehmer)
`calendar_flag_delete`	Soft-Delete: Voranstellen von "DELETE - " vor den Ereignistitel
`calendar_availability`	Überprüfen des Verfügbarkeitsstatus für einen Datumsbereich

Kontakte (2 Tools)

Tool	Beschreibung
`contacts_search`	Suche nach Kontakten nach Name, E-Mail oder Telefonnummer
`contacts_list`	Auflisten von Kontakten, optional gefiltert nach Gruppe

Multi-Account-Unterstützung

Sie können mehrere Google-Konten mit benutzerfreundlichen Namen authentifizieren:

google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"

Die meisten Tools akzeptieren einen optionalen account-Parameter. Wenn dieser weggelassen wird, wird das Standardkonto verwendet. Verwenden Sie google_status, um alle konfigurierten Konten und deren Status anzuzeigen.

Konfigurationsdateien

Die gesamte Konfiguration wird unter ~/.config/mariana-google-mcp/ gespeichert:

Datei	Zweck
`config.json`	Kontoregister (Namen, E-Mail-Hashes, Standardeinstellungen)
`tokens/<hash>.json`	OAuth-Token pro Konto (automatisch aktualisiert)
`actions.jsonl`	Nur-Anhängen-Protokoll aller Änderungen

Token werden zur Sicherheit per E-Mail-Hash gespeichert, nicht als Klartext-E-Mail.

Aktionsprotokoll

Jeder Schreibvorgang (Entwürfe, Kalendererstellungen/-aktualisierungen, Soft-Deletes) wird in ~/.config/mariana-google-mcp/actions.jsonl in diesem Format protokolliert:

{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}

Das Protokoll kann nur erweitert werden und wird vom Server niemals geändert. Überprüfen Sie es jederzeit, um zu kontrollieren, was Claude getan hat.

Forken und Verwenden

Um dies mit Ihrem eigenen Google-Konto zu verwenden:

Forken Sie dieses Repo
Erstellen Sie Ihr eigenes Google Cloud-Projekt und OAuth-Anmeldedaten (siehe Einrichtung oben)
Erstellen Sie das Projekt und verweisen Sie Ihre Claude Code-Konfiguration auf die dist/index.js Ihres Forks
Führen Sie google_auth zur Authentifizierung aus

Es sind keine Codeänderungen erforderlich – alle kontospezifischen Daten befinden sich in Konfigurationsdateien und Umgebungsvariablen.

Tech-Stack

TypeScript
@modelcontextprotocol/sdk — MCP-Protokollimplementierung
googleapis — Google API-Client
google-auth-library — OAuth2-Token-Verwaltung
zod — Eingabevalidierung

Lizenz

MIT

Mariana Google MCP