yandex-calendar-mcp

一个 MCP 服务器，让 AI 助手能够通过 CalDAV 访问 Yandex Calendar。读取日程、创建、移动和删除事件。

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

语言说明： 工具描述和响应使用俄语， 因为该服务器是为俄语助手编写的。代码、 配置和本文档使用英语。其他一切功能 与语言无关。

功能

读取

• 任意时间段的事件：默认今天，或显式指定最长 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 被列入依赖是有意为之：精简版 Linux 镜像通常 不包含时区数据库，否则 zoneinfo("Europe/Moscow") 会失败。

配置

所有配置都通过环境变量提供。

服务器通过 stdio 使用 MCP 协议。客户端配置示例见 examples/。

工具

删除不可撤销——安全保护措施

1. 标题校验。 delete_event 需要同时提供 uid 和事件标题。 两者必须匹配；不匹配则不删除任何内容，并在回复中说明 实际标题和日历。当 uid 过时或混淆时，这是 防止误删错误事件的有效手段。

2. 备份。 每次删除和每次更新之前，完整的事件 都会以带时间戳的 .ics 文件写入 YANDEX_TRASH_DIR。如果备份 写入失败，操作根本不会执行。恢复只需将该文件 重新导入即可。

3. 重复系列。 对系列的任何编辑或删除都必须明确指定 作用范围：occurrence 表示仅某一天，apply_to_series 表示整个 系列。如果两者都未指定，工具会拒绝执行并说明如何选择。这样 "取消周二" 就不会误删一整年的会议。

邀请参与者会发送真实邮件

Yandex 采用 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

已知限制

• 可以创建全天事件，但其时间无法移动。

• 重复规则只能以常见形式创建（每天 / 每周 / 每月 / 每年，带次数或结束日期）。更复杂的规则——如"每个 第二个星期二"、星期集合——可以正确读取和展开，但无法 通过工具创建。

• 不处理提醒和闹钟。

• 参与者始终被邀请为必需参加者；可选参与者 和按参与者区分的角色未开放。

• 仅针对 Yandex Calendar 验证过。其他 CalDAV 服务器很可能 可以正常工作，但未经测试。

许可证

MIT——见 LICENSE。