Apple Calendar

Name: Apple Calendar
Author: mgcrea

本地服务

cupertino.mgcrea.io生产力5今天更新

代码仓库访问官网

关于 Apple Calendar

面向 macOS Apple Calendar 的 MCP 服务，可读取日历数据并在启用写入后创建、更新或删除事件。读取与写入采用不同通道，写入工具默认不注册。

主要功能

01列出账户和日历
02按范围列出、搜索和读取事件
03启用后创建、更新和删除事件
04按账户和日历筛选读取范围

适用场景

01查询某段日期内的日程
02搜索并查看特定日历事件
03在启用写入时修改日历安排

MCP 相关

作为 MCP 服务，它向客户端提供日历诊断、账户和日历列表、事件读取与搜索工具；设置 APPLE_CALENDAR_ALLOW_WRITES=1 后才注册写入工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "mgcrea-mcp-apple-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@mgcrea/mcp-apple-calendar"
      ],
      "env": {
        "APPLE_CALENDAR_ALLOW_WRITES": "<APPLE_CALENDAR_ALLOW_WRITES>",
        "APPLE_CALENDAR_CALENDARS": "<APPLE_CALENDAR_CALENDARS>",
        "APPLE_CALENDAR_ACCOUNTS": "<APPLE_CALENDAR_ACCOUNTS>"
      }
    }
  }
}

启动命令npx -y @mgcrea/mcp-apple-calendar

需要配置的环境变量

APPLE_CALENDAR_ALLOW_WRITESRegister the mutating tools. Off by default, and the gate decides whether the write tools exist at all rather than merely refusing — an agent with writes off cannot see them.

APPLE_CALENDAR_CALENDARSRestrict every read and write to these calendars, by name.

APPLE_CALENDAR_ACCOUNTSRestrict every read and write to these Calendar accounts, by name or id. Bounds reading, not just writing.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@mgcrea/mcp-apple-calendar1.32.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

@mgcrea/mcp-apple-calendar

macOS Apple Calendar 应用的 Model Context Protocol 服务。

非官方。 与 Apple 无关。它读取 Mac 上已有的 Calendar 数据库。

读取与写入各走一条通道

索引通道 — 通过 Calendar.sqlitedb 以只读方式访问 SQLite。所有读取都经过此通道。
Apple Events 通道 — 仅用于写入。此软件包中没有 jxa/read.ts，并且有测试断言确保永远不会添加该文件。

这与 Notes 正好相反。 Notes 采用 Apple Events，是因为搜索耗时 97 ms。而 Calendar 无法这样做：通过 Apple Events 查询 ±90 天范围内的 1,349 个事件需要 3,355 ms；whose 更慢且不稳定，并且无论获取哪种属性，每次批量获取都要花费约 1.8 s，因此无法像 Notes 那样通过批量获取来分摊成本。只读打开数据库只需 1 ms。Calendar 需要文件通道来提升速度，而不是为了获得功能。

它不需要 EventKit，因此配套应用只充当纯粹的代理，无需链接会额外触发自身 TCC 权限提示的框架。

权限	用途	未授予时
完整磁盘访问权限	所有读取	所有功能都无法使用——没有读取备用方案
自动化 → Calendar	仅写入	读取不受影响

这两项权限都不授予 Calendar.app——需要权限的是读取数据的程序。将完整磁盘访问权限授予启动服务的程序（Terminal、iTerm、VS Code、Claude），然后重启服务。

默认情况下，写入功能处于关闭状态，因此完全不会出现自动化权限提示。只读 Calendar 服务只需要一项权限。

工具

读取：diagnostics、list_accounts、list_calendars、list_events、search_events、get_event。

仅当 APPLE_CALENDAR_ALLOW_WRITES=1 时才会注册写入工具——关闭该标志后，这些工具对模型不可见，而不仅仅是拒绝执行：create_event、update_event、delete_events。

配置

变量	默认值
`APPLE_CALENDAR_ALLOW_WRITES`	off	注册会修改数据的工具。
`APPLE_CALENDAR_ACCOUNTS`	all	读取端允许列表，以逗号分隔。
`APPLE_CALENDAR_CALENDARS`	all	读取端允许列表，以逗号分隔。
`APPLE_CALENDAR_DEFAULT_CALENDAR`	Calendar's	未指定日历时，新事件要添加到的日历。
`APPLE_CALENDAR_DEFAULT_RANGE_DAYS`	`7`	默认范围若不设限，就会扫描整个十年。
`APPLE_CALENDAR_MAX_RANGE_DAYS`	`366`	调用方指定的范围上限。
`APPLE_CALENDAR_DEFAULT_EVENT_DURATION_MINUTES`	`60`	写入时未指定结束时间所用的时长。
`APPLE_CALENDAR_INCLUDE_DECLINED`	off	在读取结果中包含已拒绝的事件。
`APPLE_CALENDAR_INCLUDE_CANCELLED`	off	在读取结果中包含已取消的事件。
`APPLE_CALENDAR_TIMEZONE`	system	覆盖解析日期范围时使用的时区。
`APPLE_CALENDAR_INDEX_MODE`	`auto`	`auto` \| `ro` \| `immutable` \| `off`。
`APPLE_CALENDAR_STORE`	auto	显式指定 `Calendar.sqlitedb` 路径。
`APPLE_CALENDAR_OSASCRIPT_TIMEOUT_MS`	`30000`	为首次运行时的权限提示设置的超时时长。

需要注意的问题

~/Library/Calendars 不存在。 数据库位于 ~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb。
重复事件存储在缓存表中。 在日期范围内对 CalendarItem 执行简单的 SELECT ... FROM CalendarItem 会漏掉展开后的重复事件；范围查询会将不带重复规则的项目与缓存中的所有项目合并。489 个缓存父事件中，有 456 个自身不带规则。
日期是自 2001 年起的秒数，不是自 1970 年起——CalendarItem.last_modified 和 orig_date 都是如此。
浮动时区并非系统时区。 与 GMT±HHMM 匹配的都是实际时区；将其余情况视为浮动时区，才能避免时间悄然偏移两小时。
写入始终通过 Apple Events 完成，绝不直接写入数据库，因为应用会一直打开并同步该数据库。