Google Calendar MCP

Google Kalender MCP-Server

Dies ist ein Model Context Protocol (MCP)-Server, der die Integration mit Google Kalender ermöglicht. Er ermöglicht LLMs das Lesen, Erstellen, Aktualisieren und Suchen von Kalenderereignissen über eine standardisierte Schnittstelle.

Beispielverwendung

Neben den normalen Funktionen, die Sie von einer Kalenderintegration erwarten, können Sie auch wirklich dynamische, mehrstufige Prozesse durchführen, wie:

1. Ereignisse aus Screenshots und Bildern hinzufügen:
   Add this event to my calendar based on the attached screenshot.
   Unterstützte Bildformate: PNG, JPEG, GIF. Bilder können Ereignisdetails wie Datum, Uhrzeit, Ort und Beschreibung enthalten
2. Kalenderanalyse:
   What events do I have coming up this week that aren't part of my usual routine?
3. Anwesenheitskontrolle:
   Which events tomorrow have attendees who have not accepted the invitation?
4. Ereignisse automatisch koordinieren:
   Here's some available that was provided to me by someone. Take a look at the available times and create an event that is free on my work calendar.
5. Geben Sie Ihre eigene Verfügbarkeit an:
   Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

Anforderungen

1. Node.js (neueste LTS empfohlen)
2. TypeScript 5.3 oder höher
3. Ein Google Cloud-Projekt mit aktivierter Kalender-API
4. OAuth 2.0-Anmeldeinformationen (Client-ID und Client-Geheimnis)

Google Cloud-Setup

1. Gehen Sie zur Google Cloud Console
2. Erstellen Sie ein neues Projekt oder wählen Sie ein vorhandenes aus.
3. Aktivieren Sie die Google Kalender-API für Ihr Projekt. Stellen Sie sicher, dass in der oberen Leiste das richtige Projekt ausgewählt ist, bevor Sie die API aktivieren.
4. OAuth 2.0-Anmeldeinformationen erstellen:
   • Gehe zu Anmeldeinformationen
   • Klicken Sie auf „Anmeldeinformationen erstellen“ > „OAuth-Client-ID“.
   • Wählen Sie „Benutzerdaten“ für den Datentyp, auf den die App zugreifen wird
   • Fügen Sie Ihren App-Namen und Ihre Kontaktinformationen hinzu
   • Fügen Sie die folgenden Bereiche hinzu (optional):
     • https://www.googleapis.com/auth/calendar.events (oder allgemeiner https://www.googleapis.com/auth/calendar , falls erforderlich)
   • Wählen Sie als Anwendungstyp „Desktop-App“ aus (Wichtig!)
   • Fügen Sie Ihre E-Mail-Adresse als Testbenutzer unter dem OAuth-Zustimmungsbildschirm hinzu
     • Hinweis: Es dauert einige Minuten, bis der Testbenutzer hinzugefügt wird. Die OAuth-Zustimmung ermöglicht Ihnen erst dann das Fortfahren, wenn der Testbenutzer propagiert wurde.
     • Hinweis zum Testmodus: Während sich eine App im Testmodus befindet, laufen die Authentifizierungstoken nach einer Woche ab und müssen durch Ausführen npm run auth aktualisiert werden.

Installation

1. Klonen Sie das Repository
2. Installieren Sie Abhängigkeiten (dadurch wird das JS auch per Postinstall erstellt):
   npm install
3. Laden Sie Ihre Google OAuth-Anmeldeinformationen von der Google Cloud Console (unter „Anmeldeinformationen“) herunter, benennen Sie die Datei in gcp-oauth.keys.json um und platzieren Sie sie im Stammverzeichnis des Projekts.
   • Stellen Sie sicher, dass die Datei Anmeldeinformationen für eine „Desktop-App“ enthält.
   • Alternativ können Sie die bereitgestellte Vorlagendatei kopieren: cp gcp-oauth.keys.example.json gcp-oauth.keys.json und füllen Sie sie mit Ihren Anmeldeinformationen aus der Google Cloud Console.

Verfügbare Skripte

• npm run build – Erstellen Sie den TypeScript-Code (kompiliert src zum build )
• npm run typecheck - TypeScript-Typprüfung ohne Kompilierung ausführen
• npm run start – Starten Sie den kompilierten MCP-Server (mit node build/index.js )
• npm run auth – Führen Sie den Google OAuth-Authentifizierungsfluss manuell aus.
• npm test - Führen Sie die Unit-/Integrationstestsuite mit Vitest aus
• npm run test:watch – Tests im Überwachungsmodus ausführen
• npm run coverage - Führen Sie Tests aus und generieren Sie einen Abdeckungsbericht

Authentifizierung

Der Server übernimmt die Google OAuth 2.0-Authentifizierung für den Zugriff auf Ihre Kalenderdaten.

Automatischer Authentifizierungsablauf (beim Serverstart)

1. Stellen Sie sicher, dass gcp-oauth.keys.json den richtigen Namen hat und im Projektstamm abgelegt ist.
2. Starten Sie den MCP-Server: npm start .
3. Der Server sucht in .gcp-saved-tokens.json nach vorhandenen, gültigen Authentifizierungstoken.
4. Wenn gültige Token gefunden werden, startet der Server normal.
5. Wenn keine gültigen Token gefunden werden:
   • Der Server versucht, einen temporären lokalen Webserver zu starten (er versucht es über die Ports 3000–3004).
   • Ihr Standard-Webbrowser öffnet automatisch den Anmelde- und Zustimmungsbildschirm des Google-Kontos.
   • Folgen Sie den Anweisungen im Browser, um die Anwendung zu autorisieren.
   • Nach erfolgreicher Autorisierung werden Sie auf eine lokale Seite weitergeleitet (z. B. http://localhost:3000/oauth2callback ).
   • Auf dieser Seite wird eine Erfolgsmeldung angezeigt, die bestätigt, dass die Token in .gcp-saved-tokens.json gespeichert wurden (und der genaue Dateipfad wird angezeigt).
   • Der temporäre Authentifizierungsserver wird automatisch heruntergefahren.
   • Der Haupt-MCP-Server setzt seinen Startvorgang fort.

Manueller Authentifizierungsablauf

Wenn Sie eine erneute Authentifizierung durchführen müssen oder die Authentifizierung lieber separat durchführen möchten:

1. Führen Sie den Befehl aus: npm run auth
2. Dieses Skript führt denselben browserbasierten Authentifizierungsablauf aus, der oben beschrieben wurde.
3. Ihr Browser wird geöffnet, Sie autorisieren und Ihnen wird die Erfolgsseite angezeigt, die angibt, wo die Token gespeichert wurden.
4. Das Skript wird nach erfolgreicher Authentifizierung automatisch beendet.

Token-Verwaltung

• Authentifizierungstoken werden in .gcp-saved-tokens.json im Projektstamm gespeichert.
• Diese Datei wird automatisch erstellt und sollte nicht der Versionskontrolle übergeben werden (sie ist in .gitignore enthalten).
• Der Server versucht, abgelaufene Zugriffstoken mithilfe des gespeicherten Aktualisierungstokens automatisch zu aktualisieren.
• Wenn das Aktualisierungstoken selbst abläuft (z. B. nach 7 Tagen, wenn sich die Google Cloud-App im Testmodus befindet) oder widerrufen wird, müssen Sie sich entweder über den automatischen Ablauf (durch Neustart des Servers) oder den manuellen Befehl npm run auth erneut authentifizieren.

Testen

Unit- und Integrationstests werden mit Vitest implementiert.

• Tests ausführen: npm test
• Führen Sie Tests im Überwachungsmodus aus: npm run test:watch
• Abdeckungsbericht generieren: npm run coverage

Tests simulieren externe Abhängigkeiten (Google API, Dateisystem), um isolierte Tests der Serverlogik und -handler sicherzustellen.

Sicherheitshinweise

• Der Server läuft lokal und erfordert eine OAuth-Authentifizierung.
• OAuth-Anmeldeinformationen ( gcp-oauth.keys.json ) und gespeicherte Token ( .gcp-saved-tokens.json ) sollten niemals in die Versionskontrolle übernommen werden. Stellen Sie sicher, dass sie Ihrer .gitignore Datei hinzugefügt werden.
• Erwägen Sie für den Produktionseinsatz, Ihre OAuth-Anwendung von Google verifizieren zu lassen.

Verwendung mit Claude Desktop

1. Fügen Sie diese Konfiguration zu Ihrer Claude Desktop-Konfigurationsdatei hinzu. Beispiel /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json :
   { "mcpServers": { "google-calendar": { "command": "node", "args": ["<absolute-path-to-project-folder>/build/index.js"] } } }
   Hinweis: Ersetzen Sie <absolute-path-to-project-folder> Pfad zum Projektordner> durch den tatsächlichen Pfad zu Ihrem Projektverzeichnis.
2. Starten Sie Claude Desktop neu

Entwicklung

Fehlerbehebung

1. Authentifizierungsfehler / Verbindungsrücksetzung beim Rückruf:
   • Stellen Sie sicher, dass gcp-oauth.keys.json vorhanden ist und Anmeldeinformationen für einen Desktop-App- Typ enthält.
   • Überprüfen Sie, ob Ihre Benutzer-E-Mail-Adresse in den Einstellungen des Google Cloud OAuth-Zustimmungsbildschirms als Testbenutzer hinzugefügt wurde (es kann einige Minuten dauern, bis die Änderungen wirksam werden).
   • Versuchen Sie, .gcp-saved-tokens.json zu löschen und erneut zu authentifizieren ( npm run auth oder npm start neu starten).
   • Stellen Sie sicher, dass kein anderer Prozess die Ports 3000–3004 blockiert, wenn eine Authentifizierung erforderlich ist.
2. Token verfallen wöchentlich:
   • Wenn sich Ihre Google Cloud-App im Testmodus befindet, verfallen Aktualisierungstoken nach 7 Tagen. Führen Sie bei Bedarf eine erneute Authentifizierung durch.
   • Erwägen Sie, Ihre App in der Google Cloud Console in die Produktion zu verschieben, um Aktualisierungstoken mit längerer Lebensdauer zu erhalten (erfordert eine Überprüfung durch Google).
3. Build-Fehler:
   • Führen Sie npm install erneut aus.
   • Überprüfen Sie die Node.js-Version (verwenden Sie LTS).
   • Löschen Sie das Verzeichnis build/ und führen Sie npm run build aus.

Wenn Sie Entwickler sind und zu diesem Repository beitragen möchten, werfen Sie bitte vor dem Beitrag einen Blick auf die Architekturübersicht.

Lizenz

MIT