yandex-calendar-mcp

CalDAV 経由で AI アシスタントに Yandex Calendar へのアクセスを提供する MCP サーバーです。スケジュールの読み取り、イベントの作成・移動・削除ができます。

ロシア語版

言語についての注意: ツールの説明と応答は ロシア語 です。 このサーバーはロシア語を話すアシスタント向けに書かれたためです。コード、 設定、このドキュメントは英語です。それ以外はすべて、言語に関係なく 動作します。

できること

読み取り

• 任意の期間のイベント: デフォルトは今日、または最大92日までの明示的な範囲。

• すべてのカレンダーを一度に取得し、各イベントには取得元のカレンダーがラベル付けされます。または、名前で選択した単一のカレンダーも取得できます。

• 繰り返しイベントは具体的な日付に展開されます。展開に失敗した場合は、正確なものとして提示するのではなく、警告付きでイベントが返されます。

• 参加者が、それぞれの返答状況（承諾、辞退、仮承諾、未返答）とともに一覧表示されます。

• 終日イベントは終日として認識され、深夜の予定としては表示されません。

• すべての応答には、使用されたタイムゾーンと UTC オフセットが明記されます。

書き込み

• イベントの作成: タイトル、開始、終了または所要時間、場所、説明。時刻指定または複数日にわたる終日イベント。

• 繰り返しイベントの作成 — 日次、週次、月次、または年次 — 発生回数または終了日で制限されます。

• イベントの更新: 移動、名前変更、場所や説明の変更。渡したフィールドだけが変更されます。移動したイベントは、指定しない限り元の所要時間を維持します。

• 繰り返しシリーズの 単一の出現 またはシリーズ全体を編集・削除できます。変更した日は RECURRENCE-ID の上書きになり、削除した日は EXDATE になります。これは標準的な仕組みなので、結果は Yandex アプリでも他のクライアントでも正しく表示されます。

• 参加者の招待: イベント作成時に参加者を追加でき、後から追加・削除もできます。招待メールとキャンセルメールは Yandex が自ら送信します。

• イベントの削除。ただし、後述の保護機能があります。

タイムゾーン: 意図的な処理

• すべてのタイムスタンプは zoneinfo で設定されたゾーンに変換されます。時刻文字列が文字位置で切り出されることはありません。

• 書き込まれるイベントには、明示的な DTSTART;TZID=… と完全な VTIMEZONE ブロックが含まれるため、どのカレンダークライアントでも同じように解釈されます。

• サーバーを実行しているマシンは通常 UTC ですが、それが応答に漏れることはありません。実際に使用されたゾーンがすべての応答に明記されるため、誤りがあれば黙って通り過ぎずに明らかになります。

アシスタントが操作するために設計

• 応答はイベントの uid を含む読みやすい平文テキストなので、一覧表示の後に編集や削除を直接行えます。

• create_event は明示的なカレンダーを必須とします。人々は目的別に複数のカレンダーを持っており、誤ったカレンダーに黙って登録されたイベントは失われたも同然だからです。アシスタントは推測するのではなく質問することが期待されています。

• エラーはスタックトレースではなく、次に何をすべきかを説明する文章として返されます。

Related MCP server: MCP Personal Calendar

必要条件

• Python 3.10 以降（3.13 でテスト済み）

• Yandex の アプリパスワード（アカウントのパスワードではありません）: https://id.yandex.ru/security/app-passwords → アプリの種類 "Календарь (CalDAV)"

pip install -r requirements.txt

tzdata は意図的に requirements に含まれています。スリムな Linux イメージにはタイムゾーンデータベースが含まれていないことが多く、その場合 ZoneInfo("Europe/Moscow") は失敗します。

設定

すべての設定は環境変数から取得されます。

サーバーは stdio 経由で MCP を話します。クライアント設定の例は examples/ にあります。

ツール

削除は取り消せません — そのための保護

1. タイトル確認。 delete_event は uid とイベントのタイトルの両方を受け取ります。それらが比較され、一致しない場合は何も削除されず、応答には両方のタイトルとカレンダーが示されます。古い、または誤った uid が原因で誤ったイベントを破壊するのが現実的なリスクですが、このチェックがそれを捕捉します。

2. ゴミ箱。 すべての削除 および すべての更新の前に、元のイベント全体がタイムスタンプ付きの .ics ファイルとして YANDEX_TRASH_DIR に書き込まれます。コピーが書き込めない場合、操作はまったく実行されません。復元はそのファイルを再インポートすることです。

3. 繰り返しシリーズ。 シリーズへの編集や削除は、適用対象を明示する必要があります: 1日分は occurrence、シリーズ全体は apply_to_series です。どちらも指定しない場合、ツールは拒否して選択肢を説明します。これにより、「火曜日をキャンセル」が1年分の会議を消してしまうことを防ぎます。

参加者を招待すると実際のメールが送信されます

Yandex は calendar-auto-schedule を宣伝しているため、参加者を追加するとサーバーが招待状を送信し、参加者を削除するとキャンセル通知を送信します。どちらも取り消すことはできません。これはサーバーの宣伝された機能だけでなく、エンドツーエンドで検証されています: create_event で追加された招待状が受信者のメールボックスに届きました。

そこから導かれること:

• アドレスは文字どおりに受け取られ、検証されます。サーバーは名前からアドレスを導出することはありません。そうしないと、連絡先を曖昧に覚えているアシスタントが見知らぬ人にメールを送ってしまうからです。

• update_event は参加者リストを置き換えるのではなく、参加者を 追加および削除 するため、他の参加者がすでに返した回答は保持されます。

• すべての応答には、イベントに誰が参加していて、それぞれがどう返答したかが正確に記載されるため、誤ったアドレスはすぐにわかります。

このサーバーを操作するアシスタントは、呼び出し前にユーザーとアドレスリストを確認すべきです。招待状の送信は取り消しできない操作です。

テスト

python tests/write_cycle.py "Calendar name"

実際のプロトコルを通じて実際のカレンダーに対して行う自己クリーンアップの一連のテストです。単発イベント: 作成 → 誤ったタイトルでの削除を試行（拒否されること）→ 移動と名前変更 → 一覧に表示されることを確認 → 削除 → 消えたことを確認。3回発生するシリーズ: 1日分を編集、1日分を削除、シリーズ全体を削除し、そのたびに正確に1日だけが変更されたことを確認します。削除に失敗した場合、残ったイベントの uid が黙って放置されるのではなく出力されます。

参加者のテストは、実際のメールを送信するため、アドレスが明示的に渡された場合にのみ実行されます:

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

tests/probe.jsonl は、ハンドシェイクと読み取りパスを確認するための生のプロトコルメッセージのセットです:

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

既知の制限

• 終日イベントは作成できますが、その時刻を移動することはできません。

• 繰り返しルールは一般的な形式（毎日 / 毎週 / 毎月 / 毎年、回数または終了日付き）で作成できます。より複雑なルール — 「毎月第2火曜日」や曜日のセットなど — は正しく読み取り・展開できますが、ツールからは作成できません。

• リマインダーとアラームには対応していません。

• 参加者は常に必須参加者として招待されます。任意参加者や参加者ごとの役割は公開されていません。

• Yandex Calendar に対してのみ検証済みです。他の CalDAV サーバーでも動作する可能性は高いですが、テストされていません。

ライセンス

MIT — LICENSE を参照してください。