yandex-calendar-mcp

Ein MCP-Server, der einem KI-Assistenten Zugriff auf Yandex Calendar über CalDAV gibt. Termine lesen, erstellen, verschieben und löschen.

Русская версия

Hinweis zur Sprache: Tool-Beschreibungen und Antworten sind auf Russisch, da der Server für einen russischsprachigen Assistenten geschrieben wurde. Der Code, die Konfiguration und dieses Dokument sind auf Englisch. Alles andere funktioniert unabhängig von der Sprache.

Was es tut

Lesen

• Ereignisse für einen beliebigen Zeitraum: standardmäßig heute oder ein expliziter Bereich bis zu 92 Tagen.

• Alle Kalender auf einmal, wobei jedes Ereignis mit dem Kalender gekennzeichnet ist, aus dem es stammt – oder ein einzelner Kalender, der nach Namen ausgewählt wird.

• Wiederkehrende Ereignisse werden in konkrete Daten aufgelöst. Wenn die Auflösung fehlschlägt, wird das Ereignis mit einer Warnung zurückgegeben, anstatt als korrekt dargestellt zu werden.

• Teilnehmer werden mit ihrer Antwort aufgelistet – angenommen, abgelehnt, vorläufig oder noch keine Antwort.

• Ganztägige Ereignisse werden als solche erkannt und nicht als Mitternachtstermine angezeigt.

• Jede Antwort nennt die Zeitzone und den UTC-Offset, die verwendet wurden.

Schreiben

• Ein Ereignis erstellen: Titel, Start, Ende oder Dauer, Ort, Beschreibung; zeitgesteuert oder ganztägig über mehrere Tage.

• Ein wiederkehrendes Ereignis erstellen – täglich, wöchentlich, monatlich oder jährlich – begrenzt durch eine Anzahl von Vorkommen oder durch ein Enddatum.

• Ein Ereignis aktualisieren: verschieben, umbenennen, Ort oder Beschreibung ändern. Nur die übergebenen Felder werden geändert; ein verschobenes Ereignis behält seine ursprüngliche Dauer, sofern nicht anders angegeben.

• Ein einzelnes Vorkommen einer wiederkehrenden Serie bearbeiten oder löschen, oder die gesamte Serie. Ein geänderter Tag wird zu einem RECURRENCE-ID-Override, ein entfernter Tag zu einer EXDATE – die Standardmechanismen, sodass das Ergebnis in der Yandex-App und in jedem anderen Client korrekt aussieht.

• Personen einladen: Teilnehmer können beim Erstellen eines Ereignisses hinzugefügt und später hinzugefügt oder entfernt werden. Yandex verschickt die Einladungen und Stornierungen selbst.

• Ein Ereignis löschen, mit den unten beschriebenen Sicherheitsvorkehrungen.

Zeitzonen, bewusst behandelt

• Jeder Zeitstempel wird mit zoneinfo in die konfigurierte Zone umgewandelt. Zeitzeichenfolgen werden niemals nach Zeichenposition aufgeteilt.

• Geschriebene Ereignisse tragen eine explizite DTSTART;TZID=…-Angabe plus einen vollständigen VTIMEZONE-Block, sodass jeder Kalender-Client sie gleich liest.

• Die Maschine, auf der der Server läuft, ist normalerweise auf UTC; das leckt nie in die Antworten, und die tatsächlich verwendete Zone wird in jeder Antwort genannt, sodass ein Fehler sichtbar statt still ist.

Für einen Assistenten gebaut

• Antworten sind einfacher lesbarer Text mit der Ereignis-uid, sodass eine Bearbeitung oder Löschung direkt auf eine Auflistung folgen kann.

• create_event erfordert einen expliziten Kalender: Menschen führen mehrere Kalender für verschiedene Zwecke, und ein Ereignis, das stillschweigend in den falschen Kalender einsortiert wird, ist ein verlorenes Ereignis. Der Assistent soll fragen, nicht raten.

• Fehler kommen als Sätze zurück, die erklären, was als Nächstes zu tun ist, nicht als Stack-Traces.

Related MCP server: MCP Personal Calendar

Anforderungen

• Python 3.10 oder neuer (3.13 getestet)

• Ein Yandex-App-Passwort, nicht das Kontopasswort: https://id.yandex.ru/security/app-passwords → Anwendungstyp "Календарь (CalDAV)"

pip install -r requirements.txt

tzdata ist absichtlich in den Anforderungen enthalten: Schlanke Linux-Images werden oft ohne Zeitzonendatenbank ausgeliefert, und ZoneInfo("Europe/Moscow") schlägt dann fehl.

Konfiguration

Alle Einstellungen kommen aus Umgebungsvariablen.

Der Server spricht MCP über stdio. Eine Beispiel-Client-Konfiguration finden Sie in examples/.

Werkzeuge

Löschen ist unumkehrbar – was Sie schützt

1. Titelprüfung. delete_event erfordert sowohl die uid als auch den Ereignistitel. Sie werden verglichen; bei Nichtübereinstimmung wird nichts gelöscht und die Antwort nennt beide Titel und den Kalender. Eine veraltete oder verwechselte uid ist der realistische Weg, das falsche Ereignis zu zerstören, und genau das fängt dies ab.

2. Papierkorb. Vor jedem Löschen und jeder Aktualisierung wird das vollständige Originalereignis als zeitgestempelter .ics-Datei in YANDEX_TRASH_DIR geschrieben. Wenn die Kopie nicht geschrieben werden kann, wird der Vorgang überhaupt nicht ausgeführt. Die Wiederherstellung erfolgt durch Import dieser Datei.

3. Wiederkehrende Serien. Jede Bearbeitung oder Löschung einer Serie muss angeben, worauf sie sich bezieht: occurrence für einen Tag, apply_to_series für die gesamte Serie. Ohne beides verweigert das Tool und erklärt die Wahl. Das verhindert, dass „Dienstag absagen“ ein Jahr voller Besprechungen löscht.

Personen einladen sendet echte E-Mails

Yandex bewirbt calendar-auto-schedule, sodass das Hinzufügen eines Teilnehmers den Server veranlasst, eine Einladung zu senden, und das Entfernen eines Teilnehmers eine Stornierung sendet. Beides kann nicht zurückgerufen werden. Dies wurde Ende-zu-Ende verifiziert, nicht nur anhand der beworbenen Fähigkeiten des Servers: Eine über create_event hinzugefügte Einladung kam im Postfach des Empfängers an.

Daraus folgt:

• Adressen werden wörtlich genommen und validiert. Der Server leitet niemals eine Adresse aus einem Namen ab – ein Assistent, der sich halb an einen Kontakt erinnert, würde sonst einem Fremden eine E-Mail senden.

• update_event fügt Teilnehmer hinzu und entfernt sie, anstatt die Liste zu ersetzen, sodass bereits gegebene Antworten der anderen erhalten bleiben.

• Jede Antwort listet genau auf, wer an dem Ereignis beteiligt ist und wie sie geantwortet haben, sodass eine falsche Adresse sofort sichtbar ist.

Ein Assistent, der diesen Server steuert, sollte die Adressliste mit seinem Benutzer bestätigen, bevor er aufruft. Das Senden einer Einladung ist keine rückgängig zu machende Aktion.

Testen

python tests/write_cycle.py "Calendar name"

Selbstreinigende Runden gegen einen echten Kalender über das tatsächliche Protokoll. Ein einmaliges Ereignis: erstellen → versuchen, mit falschem Titel zu löschen (muss abgelehnt werden) → verschieben und umbenennen → bestätigen, dass es in der Auflistung erscheint → löschen → bestätigen, dass es weg ist. Eine Serie mit drei Vorkommen: einen Tag bearbeiten, einen Tag löschen, die gesamte Serie löschen, wobei jedes Mal überprüft wird, dass genau ein Tag geändert wurde. Wenn ein Löschen fehlschlägt, wird die uid des übrig gebliebenen Ereignisses ausgegeben, anstatt stillschweigend zurückgelassen zu werden.

Die Teilnehmerrunde läuft nur, wenn eine Adresse explizit übergeben wird, da sie echte E-Mails sendet:

python tests/write_cycle.py "Calendar name" someone@example.com

tests/probe.jsonl ist eine Reihe von rohen Protokollnachrichten zur Überprüfung des Handshakes und des Lesepfads:

python src/server.py < tests/probe.jsonl

Bekannte Einschränkungen

• Ganztägige Ereignisse können erstellt werden, aber ihre Zeit kann nicht verschoben werden.

• Wiederholungsregeln werden in ihren üblichen Formen erstellt (täglich / wöchentlich / monatlich / jährlich, mit einer Anzahl oder einem Enddatum). Aufwändigere Regeln – „jeden zweiten Dienstag“, Wochentagsmengen – werden korrekt gelesen und erweitert, können aber nicht über das Tool erstellt werden.

• Erinnerungen und Alarme werden nicht behandelt.

• Teilnehmer werden immer als erforderliche Teilnehmer eingeladen; optionale Teilnehmer und Rollen pro Teilnehmer werden nicht offengelegt.

• Nur gegen Yandex Calendar verifiziert. Andere CalDAV-Server funktionieren wahrscheinlich, sind aber ungetestet.

Lizenz

MIT – siehe LICENSE.