Ida-Google

Ein eigenständiger MCP-Server (Model Context Protocol) für Google-Dienste -- getrennt von Ida-Untis, Ida-Telegram und Ida-Memory, eigenes Repo, eigener Container. Gibt Claude 54 Werkzeuge für Google Tasks, Kontakte, Kalender, Gmail, Docs, Sheets, Slides, Chat und Meet, mit mehr Diensten in kommenden Ausbaustufen (siehe Fahrplan unten). Ziel ist, ueber die Zeit moeglichst alles abzudecken, was die jeweilige Google-API hergibt -- nicht nur eine kleine Grundauswahl.

Bewusst als ein einziger, einheitlicher Connector gebaut -- auch dort, wo es (z.B. für Kalender, Gmail-Lesen, Drive) schon offizielle claude.ai- Connectors gibt. Eine echte Ergänzung dazu: google_mail_senden kann tatsächlich senden, nicht nur lesen/entwerfen wie der offizielle Gmail-Connector.

Architektur: zwei Ports, zwei Vertrauenszonen

Google-Zugriff läuft über OAuth: einmalig im Browser bei Google anmelden und zustimmen, danach läuft alles automatisiert über einen gespeicherten Refresh-Token. Diese zwei Dinge -- der einmalige Browser-Anmelde-Flow und die laufenden, automatisierten API-Aufrufe -- laufen bewusst auf zwei getrennten Ports/Hostnamen mit unterschiedlichem Schutz:

Browser (nur du)                    Claude / eine Routine
      |                                     |
      v                                     v
auth.deine-domain.de              google.deine-domain.de
  (Cloudflare Zero Trust Access)     (normaler Cloudflare Tunnel)
      |                                     |
      v                                     v
127.0.0.1:4570 (Auth-Port)        127.0.0.1:4569 (MCP-Port)
  /authorize, /oauth/callback        /mcp (Bearer-Token)
      |                                     |
      +----------------+--------------------+
                        v
         Docker-Container "ida-google-mcp"
                        |
                        v
       /data/google_token.json (Docker-Volume)

• Auth-Port (4570): nur für den (seltenen) Google-Anmelde-Flow. Diese Hostname-Route sollte zusätzlich hinter Cloudflare Zero Trust Access liegen (eigene Cloudflare-Funktion, verlangt einen Login -- z.B. per E-Mail-Code -- bevor die Anfrage überhaupt beim Server ankommt), damit wirklich nur du diesen Flow je starten kannst. Ein zweites, kostenloses Sicherheitsnetz (AUTH_TOKEN als ?token=) ist zusätzlich eingebaut, ersetzt Zero Trust Access aber nicht.
• MCP-Port (4569): die eigentlichen Google-Werkzeuge, ganz normal per Bearer-Token abgesichert wie bei den anderen drei Ida-*-Projekten -- läuft dauerhaft, keine Browser-Interaktion nötig.

Beide Ports laufen im selben Container/Prozess (app/main.py) und teilen sich denselben gespeicherten Refresh-Token.

Voraussetzungen

• Docker + Docker Compose auf dem Server
• Ein bereits eingerichteter und verbundener Cloudflare Tunnel
• Cloudflare Zero Trust (kostenlos bis 50 Nutzer) für den Auth-Port
• Ein Google-Cloud-Projekt mit OAuth-Client (Anleitung in .env.example)

1. Google Cloud Console einrichten

Ausführliche Schritt-für-Schritt-Anleitung steht direkt in .env.example (OAuth-Zustimmungsbildschirm, benötigte APIs aktivieren, OAuth-Client anlegen). Kurzfassung: neues Projekt -> Zustimmungsbildschirm (extern, dich selbst als Testnutzer) -> benötigte APIs aktivieren (aktuell: Google Tasks API, People API, Google Calendar API, Gmail API, Google Keep API, Google Docs API, Google Sheets API, Google Slides API, Google Chat API, Google Meet API) -> OAuth-Client vom Typ "Webanwendung" mit der Redirect-URI https://auth.deine-domain.de/oauth/callback.

Nach jedem Update, das neue Google-Dienste oder zusätzliche Berechtigungen für bestehende Dienste hinzufügt: einmal erneut /authorize?token=... aufrufen, damit auch den neuen/erweiterten Scopes zugestimmt wird -- sonst melden betroffene Tools "insufficient authentication scopes". Bereits funktionierende Tools sind davon nicht betroffen.

2. Einrichten, bauen, starten

git clone https://github.com/<dein-user>/Ida-Google.git
cd Ida-Google
cp .env.example .env

.env ausfüllen (siehe Kommentare darin). Image bauen lassen: Bei jedem Push auf main baut .github/workflows/docker-publish.yml automatisch nach ghcr.io/<dein-user>/ida-google:latest. Einmalig auf öffentlich stellen (GitHub -> Profil -> Packages -> ida-google -> Package settings -> Change visibility -> Public).

docker compose pull
docker compose up -d
docker compose logs -f

3. An den bestehenden Cloudflare Tunnel anbinden -- zwei Hostnamen

ingress:
  - hostname: google.deine-domain.de
    service: http://localhost:4569
  - hostname: auth.deine-domain.de
    service: http://localhost:4570
  - service: http_status:404

Danach in Cloudflare Zero Trust (dash.teams.cloudflare.com) -> Access -> Applications -> "Add an application" -> Self-hosted -> Domain auth.deine-domain.de -> eine Policy, die nur deine eigene E-Mail-Adresse zulässt. Ab dann verlangt Cloudflare selbst einen Login, bevor /authorize überhaupt erreichbar ist. google.deine-domain.de (der MCP-Port) braucht diese Policy nicht -- der ist ganz normal per Bearer-Token abgesichert und soll ja von Claude/Routinen erreichbar bleiben.

4. Einmalig mit Google verbinden

Im Browser aufrufen (löst den Login bei Cloudflare Access aus, falls konfiguriert):

https://auth.deine-domain.de/authorize?token=<AUTH_TOKEN>

Google-Consent-Screen bestätigen ("Nicht verifiziert" ist normal für eine private App wie diese). Danach zeigt die Seite "Erfolgreich mit Google verbunden".

5. Als claude.ai Connector hinzufügen

claude.ai -> Einstellungen -> Connectors -> Add custom connector -> als URL:

https://google.deine-domain.de/mcp?token=<MCP_AUTH_TOKEN>

Verfügbare MCP-Tools (55)

Vollständige Parameter/Docstrings direkt im Code (app/services/*.py) -- hier nur eine Übersicht nach Dienst gruppiert.

Dienst	Tools	Kann u.a.
Verbindung	google_verbindung_status	Prüft, ob überhaupt mit Google verbunden
Tasks	5	Listen/Aufgaben lesen, anlegen, erledigt markieren, löschen
Kontakte	5	Lesen, anlegen, bearbeiten, löschen
Kalender	4	Termine lesen/anlegen/ändern/löschen, Teilnehmer einladen (echte Google-Einladungsmail)
Gmail	14	Suchen, lesen, senden mit CC/BCC/Anhängen/wählbarem Absender, im Thread antworten, Anhänge herunterladen (Bilder als echtes Bild), Labels lesen/erstellen/anwenden/entfernen, Entwürfe anlegen/lesen/senden, in den Papierkorb verschieben, konfigurierte "Senden als"-Adressen auflisten
Docs	7	Anlegen, lesen, Text anhängen/an Position einfügen/löschen, Suchen & Ersetzen, Fett/Kursiv/Unterstrichen
Sheets	8	Anlegen, Bereich lesen/schreiben/anhängen/leeren, Tabellenblatt anlegen/umbenennen/löschen
Slides	5	Anlegen, lesen, Titel+Text-Folie hinzufügen/löschen/verschieben
Chat	4	Räume auflisten, Raum erstellen, Nachricht senden, Nachrichten lesen
Meet	2	Meeting-Raum anlegen (Beitritts-Link), Details abrufen

Google-Fehler (fehlender Scope, abgelaufene Berechtigung, API nicht aktiviert, ...) kommen 1:1 mit Googles eigener Fehlermeldung zurück, statt geraten zu werden.

Mail über eine andere Absenderadresse schicken

Wer bei Gmail mehrere "Senden als"-Adressen eingerichtet hat (Gmail -> Einstellungen -> Konten -> "Senden als"), kann den optionalen Parameter von bei google_mail_senden/google_mail_antworten/ google_mail_entwurf_erstellen nutzen, um eine dieser Adressen statt der Hauptadresse zu verwenden. google_mail_absender_liste zeigt, welche Adressen konfiguriert und verifiziert sind -- nur verifizierte Adressen funktionieren tatsächlich, alles andere ignoriert Gmail und nimmt automatisch die Hauptadresse. Neue "Senden als"-Adressen selbst einrichten geht weiterhin nur direkt in den Gmail-Einstellungen, nicht über dieses Tool.

Bestätigungspflicht beim Löschen

Jedes Tool, das Daten unwiderruflich entfernt (Name endet auf _loeschen, dazu google_mail_papierkorb und google_sheet_bereich_leeren), hat einen Parameter bestaetigt (Standard False). Ohne bestaetigt=True passiert technisch nichts -- das Tool gibt nur einen Hinweis zurück, was gelöscht würde. Claude ist angewiesen, immer erst im Chat nachzufragen und dann mit bestaetigt=True zu wiederholen. Das ist codeseitig erzwungen, nicht nur eine Anweisung, der die KI folgen könnte oder auch nicht.

Ausnahme: google_termin_loeschen (Kalender-Termine). Der hat gar keinen bestaetigt-Parameter und löscht sofort -- ausdrücklich so gewünscht, damit Terminänderungen schnell gehen.

Mail-/Chat-Versand (google_mail_senden, google_mail_antworten, google_mail_entwurf_senden, google_chat_nachricht_senden) hat keinen codeseitigen Schutz (das würde bedeuten, doppelt aufrufen zu müssen, nur um einmal zu senden) -- dafür weisen die Server-instructions Claude an, den Inhalt vor dem Senden im Chat zu bestätigen.

Fahrplan

Ziel ist moeglichst vollstaendige Abdeckung jeder angebundenen API, nicht nur eine Grundauswahl -- wird schrittweise erweitert, mit jeweils eigener Testrunde. Bekannte, noch offene Lücken:

• Gmail: Filter/Regeln verwalten, mehrere Anhänge pro Downloadaufruf.
• Docs: Bilder, Tabellen, Kommentare/Vorschläge, Aufzählungslisten.
• Sheets: Zellformatierung (Farben/Schrift), Diagramme, Sortieren/Filtern, Pivot-Tabellen.
• Slides: freies Layout (Bilder, Positionierung, eigene Designs statt nur Titel+Text).
• Kontakte: Kontaktgruppen, Volltextsuche über searchContacts.
• Meet: Teilnehmerlisten, Aufzeichnungen/Transkripte (conferenceRecords).
• Neue Dienste: YouTube, Apps Script.

Google Keep ist deaktiviert (Code liegt in app/services/notes.py, aber nicht in _SERVICE_MODULES eingehängt): Googles eigene Doku beschreibt die Keep API als für Unternehmensumgebungen gedacht, und ein echter Authorize-Versuch mit einem privaten Google-Konto wurde von Google mit invalid_scope abgelehnt. Kommt zurück, falls sich das mal ändert (z.B. mit einem Workspace-Konto).

Danach die weiteren eingeschränkten Dienste, wenn das jeweils zutrifft: Google Ads (braucht einen von Google genehmigten Developer-Token), Workspace Admin SDK (braucht ein bezahltes Workspace-Konto mit Admin-Rechten), Classroom (braucht echte Classroom-Nutzung), Google Photos (seit einer Google-Richtlinienänderung eingeschränkter Lesezugriff für nicht verifizierte Apps).

Ob Chat und Meet mit einem normalen privaten Google-Konto (statt einem bezahlten Workspace-Konto) vollständig funktionieren, ließ sich nicht vorab zweifelsfrei klären -- das zeigt sich beim ersten echten Aufruf über Googles eigene Fehlermeldung, statt hier geraten zu werden.

Lokal testen ohne Cloudflare

docker compose up -d
curl "http://127.0.0.1:4570/healthz"
curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://127.0.0.1:4569/healthz

Troubleshooting

• Container startet nicht: docker compose logs -- meist fehlt eine Pflichtvariable in .env (GOOGLE_CLIENT_ID/_SECRET/GOOGLE_REDIRECT_URI).
• Tool meldet "Noch nicht mit Google verbunden": Schritt 4 (einmaliger Anmelde-Flow) noch nicht gemacht, oder der Container wurde ohne das /data-Volume neu gestartet (docker compose down -v löscht auch den gespeicherten Token -- ohne -v starten).
• "Google hat keinen Refresh-Token geliefert": Google gibt nur beim ersten Zustimmen (oder mit prompt=consent, was hier immer gesetzt ist) einen Refresh-Token zurück. Falls es trotzdem passiert: unter myaccount.google.com/permissions den Zugriff dieser App entfernen und /authorize erneut aufrufen.
• Google-API-Fehler "insufficient authentication scopes" o.ä.: Nach einem Update, das neue/erweiterte Berechtigungen braucht, muss /authorize erneut aufgerufen werden, damit die neuen Scopes mit zugestimmt werden.
• Google-API-Fehler "invalid_scope" beim Aufrufen von /authorize: einer der angeforderten Scopes lässt sich für diesen Google-Account/dieses Cloud-Projekt nicht vergeben (z.B. Keep, siehe Fahrplan) -- betrifft dann die komplette Anmeldung, da alle Scopes zusammen angefragt werden. In app/server.py das entsprechende Modul aus _SERVICE_MODULES entfernen.
• Lösch-Tool antwortet nur mit einem Hinweis, löscht aber nichts: so gewollt -- erst mit bestaetigt=True erneut aufrufen (siehe Bestätigungspflicht beim Löschen).
• Claude/eine KI bekommt 401 auf dem MCP-Port: Token in Client-Konfiguration und .env vergleichen.