Apple Calendar

apple-calendar-mcp

一个 MCP 服务，可让 AI 助手读取和创建 Apple Calendar 中的事件，还能帮你找出实际有空的时间。

仅限 macOS。 它使用 EventKit（Apple 自家的日历框架），该框架没有跨平台替代方案。

claude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcp

无需 Xcode、Swift 工具链，也无需克隆仓库。已签名的辅助程序二进制文件随软件包一同提供。

功能

大多数日历集成只能回答我的日历上有什么安排。它还能回答我什么时候有空：

"Find me two hours for deep work this week, outside meetings"
"When could I fit a 30-minute call with someone in Berlin?"
"Book focus time Thursday morning"

find_free_time 返回空闲时段，而不是忙碌时段。它知道“工作”指工作日的工作时间，“个人”指任何一天，并且全天事件通常不应算作忙碌。

它还可以在每场会议前后留出缓冲时间，因为两通电话之间紧挨着的空档，虽然纸面上有空，实际上却派不上用场。

除此之外，也提供常见功能：列出日历、读取指定时间范围内的事件（可选文本搜索）、创建、更新和删除事件，并支持地点、备注、提醒、全天或定时事件。重复事件会作为单独的发生实例返回，而不是作为主事件返回——这是基于 AppleScript 的服务常常处理错误的细节。

更改或删除重复事件的某个发生实例时，必须明确说明是仅针对该实例，还是也包括此后所有实例。这里没有默认选项，因为“取消这个星期二的安排”和“以后都不再安排”可不是能随便猜的事。

完整参数参考：docs/tools.md。

要求

• macOS 14（Sonoma）或更高版本
• Node.js 20 或更高版本

除此之外别无要求。从源代码构建还需要 Xcode Command Line Tools，但从 npm 安装则不需要。

设置

1. 将服务添加到客户端。

claude mcp add apple-calendar -- npx -y @redpop/apple-calendar-mcp

{
  "mcpServers": {
    "apple-calendar": {
      "command": "npx",
      "args": ["-y", "@redpop/apple-calendar-mcp"]
    }
  }
}

2. 首次使用时授予日历访问权限。

向助手提问：“我有哪些日历？” 系统会弹出对话框，询问是否允许 calendar-helper（而非你的助手，是辅助程序本身）访问日历。

确认后，打开 系统设置 → 隐私与安全性 → 日历 → calendar-helper → 选项…，并确保选中 完全访问权限，而不是“仅添加”。仅有只读权限并不足够；辅助程序会在启动时检查是否拥有完全访问权限。

这是唯一需要手动操作的步骤，任何软件包格式都无法绕过它。对话框只会出现一次，更新后也仍然有效。

为什么对话框显示“calendar-helper”

macOS 会将日历权限授予负责的父进程，而不是实际发起请求的程序。因此，如果 AI 客户端在其应用包中未声明使用日历，它启动的所有程序都会被锁在外面——没有任何提示，也不会在系统设置中显示相关条目。一些 MCP 日历服务会通过要求你从终端启动客户端来绕过这个问题。

这个服务无需这样做。辅助程序会在启动时放弃继承来的责任，并成为独立的权限主体，因此 macOS 会从它自己的应用包中读取使用说明，并以它自己的名称请求权限。授予一次权限后，这台设备上的所有客户端都能使用。

完整说明：docs/architecture.md。

更新

npx -y @redpop/apple-calendar-mcp@latest

更新不会影响你的日历授权：辅助程序会安装到固定路径，macOS 会将授权绑定到该路径，而不是绑定到二进制文件的内容。

卸载

从客户端的 MCP 配置中移除 apple-calendar 条目，然后重启客户端。接着删除辅助程序及其权限：

rm -rf ~/Library/Application\ Support/apple-calendar-mcp

系统设置 → 隐私与安全性 → 日历 下的条目仍会保留——即使二进制文件已不存在，macOS 也会保留这些条目。如果想撤销权限，可在那里将其关闭。

从源代码构建

git clone https://github.com/redpop/apple-calendar-mcp.git
cd apple-calendar-mcp
npm install && npm run build && ./swift/build.sh

然后让客户端使用 node 指向 dist/index.js，而不是使用 npx。如果没有 Developer ID 证书，辅助程序会使用临时签名，因此 macOS 会将日历权限绑定到确切的构建版本——每次重新构建后都需要重新授权。

了解更多

• docs/architecture.md — 两个部分如何协同工作，以及完整的 TCC 权限说明
• docs/tools.md — 每个工具的参数、默认值以及全天事件的提醒规则
• docs/cli.md — 独立的 calendar-helper 命令，可用于在没有 MCP 客户端的情况下进行测试
• docs/troubleshooting.md — 常见错误及其解决方法

隐私

所有操作都在本地进行。日历数据从 EventKit 传递给辅助程序，再传递给 MCP 服务和客户端，不会流向其他地方。此项目不包含任何网络代码。

许可证

MIT — 参见 LICENSE。