yandex-calendar-mcp

MCP-сервер, который даёт ИИ-ассистенту доступ к Яндекс Календарю по CalDAV. Читайте расписание, создавайте, перемещайте и удаляйте события.

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

Примечание о языке: описания инструментов и ответы — на русском, потому что сервер написан для русскоязычного ассистента. Код, конфигурация и этот документ — на английском. Всё остальное работает независимо от языка.

Что умеет

Чтение

• События за любой период: по умолчанию сегодня, либо явный диапазон до 92 дней.

• Сразу все календари, и каждое событие помечено календарём, из которого оно пришло, — или один календарь, выбранный по имени.

• Повторяющиеся события разворачиваются в конкретные даты. Если разворачивание не удалось, событие возвращается с предупреждением, а не выдаётся за точное.

• Участники перечислены с их ответами — принял, отклонил, предварительно или пока без ответа.

• События на весь день распознаются как таковые и не показываются как встречи в полночь.

• Каждый ответ указывает часовой пояс и смещение UTC, которые использовались.

Запись

• Создание события: название, начало, конец или длительность, место, описание; событие с временем или на весь день, в том числе на несколько дней.

• Создание повторяющегося события — ежедневно, еженедельно, ежемесячно или ежегодно — с ограничением по числу повторений или по дате окончания.

• Обновление события: перенести, переименовать, изменить место или описание. Затрагиваются только переданные поля; перенесённое событие сохраняет исходную длительность, если не указано иное.

• Редактирование или удаление отдельного вхождения повторяющейся серии или всей серии. Изменённый день становится переопределением RECURRENCE-ID, удалённый — EXDATE. Это стандартные механизмы, поэтому результат корректно выглядит в приложении Яндекс и в любом другом клиенте.

• Приглашение людей: участников можно добавить при создании события, а также добавить или удалить позже. Яндекс сам отправляет приглашения и уведомления об отмене.

• Удаление события с защитными механизмами, описанными ниже.

Часовые пояса — осознанно

• Каждая метка времени преобразуется в настроенный пояс с помощью zoneinfo. Строки времени никогда не режутся по позиции символов.

• Записанные события содержат явный DTSTART;TZID=… и полный блок VTIMEZONE, поэтому любой календарный клиент читает их одинаково.

• Машина, на которой работает сервер, обычно находится в UTC; это никогда не просачивается в ответы, а фактически используемый пояс назван в каждом ответе, поэтому ошибка видна, а не остаётся незамеченной.

Создан для управления ассистентом

• Ответы — это обычный читаемый текст с uid события, поэтому после списка можно сразу выполнить редактирование или удаление.

• create_event требует явного указания календаря: у людей бывает несколько календарей для разных целей, и событие, молча попавшее не в тот календарь, считается потерянным. Ожидается, что ассистент спросит, а не будет угадывать.

• Ошибки возвращаются в виде предложений с объяснением, что делать дальше, а не в виде стектрейсов.

Related MCP server: MCP Personal Calendar

Требования

• Python 3.10 или новее (проверено на 3.13)

• Пароль приложения Яндекса app password, а не пароль от аккаунта: https://id.yandex.ru/security/app-passwords → тип приложения "Календарь (CalDAV)"

pip install -r requirements.txt

tzdata включён в зависимости намеренно: урезанные Linux-образы часто поставляются без базы часовых поясов, и тогда ZoneInfo("Europe/Moscow") падает.

Конфигурация

Все настройки задаются через переменные окружения.

Сервер общается по MCP через stdio. Пример конфигурации клиента — в examples/.

Инструменты

Удаление необратимо — что вас защищает

1. Проверка названия. delete_event принимает и uid, и название события. Они сравниваются; при несовпадении ничего не удаляется, а в ответе названы оба заголовка и календарь. Устаревший или перепутанный uid — реальный способ удалить не то событие, и именно это здесь отлавливается.

2. Корзина. Перед каждым удалением и каждым обновлением полное исходное событие записывается в YANDEX_TRASH_DIR в виде .ics-файла с меткой времени. Если копию записать не удалось, операция не выполняется вовсе. Восстановление — импорт этого файла обратно.

3. Повторяющиеся серии. Любое изменение или удаление серии должно указывать, к чему оно относится: occurrence — для одного дня, apply_to_series — для всей серии. Если не указано ни то, ни другое, инструмент отказывается и объясняет выбор. Именно это не даёт «отменить вторник» стереть год встреч.

Приглашение людей отправляет настоящие письма

Яндекс заявляет поддержку calendar-auto-schedule, поэтому добавление участника заставляет сервер отправить приглашение, а удаление — уведомление об отмене. Ни то, ни другое нельзя отозвать. Это проверено от начала до конца, а не только по заявленным возможностям сервера: приглашение, добавленное через create_event, пришло в почтовый ящик получателя.

Что из этого следует:

• Адреса принимаются буквально и проверяются. Сервер никогда не выводит адрес из имени — иначе ассистент, который смутно помнит контакт, написал бы незнакомцу.

• update_event добавляет и удаляет участников, а не заменяет список, поэтому уже данные остальными ответы сохраняются.

• Каждый ответ перечисляет, кто именно в событии и как ответил, поэтому неверный адрес виден сразу.

Ассистент, управляющий этим сервером, должен подтвердить список адресов с пользователем перед вызовом. Отправка приглашения — это действие, которое нельзя отменить.

Тестирование

python tests/write_cycle.py "Calendar name"

Самозачищающиеся прогоны на реальном календаре через настоящий протокол. Разовое событие: создать → попытаться удалить с неверным названием (должен быть отказ) → перенести и переименовать → убедиться, что оно появилось в списке → удалить → убедиться, что его нет. Серия из трёх вхождений: изменить один день, удалить один день, удалить всю серию, каждый раз проверяя, что изменился ровно один день. Если удаление не удалось, uid оставшегося события печатается, а не остаётся молча.

Прогон с участниками выполняется только тогда, когда адрес передан явно, потому что он отправляет настоящие письма:

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

tests/probe.jsonl — набор сырых сообщений протокола для проверки рукопожатия и пути чтения:

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

Известные ограничения

• События на весь день можно создавать, но их время нельзя перенести.

• Правила повторения создаются в их распространённых формах (каждый день / неделю / месяц / год, с количеством или датой окончания). Более сложные правила — «каждый второй вторник», наборы дней недели — читаются и разворачиваются корректно, но через инструмент их создать нельзя.

• Напоминания и сигналы не обрабатываются.

• Участники всегда приглашаются как обязательные; опциональные участники и роли отдельных участников не раскрываются.

• Проверено только с Яндекс Календарём. Другие CalDAV-серверы, вероятно, заработают, но не тестировались.

Лицензия

MIT — см. LICENSE.