Apple Calendar MCP

Apple Calendar MCP 让 AI 客户端对一个 iCloud Calendar 账户拥有远程读写权限。它作为 Cloudflare 上的无状态 TypeScript Worker 运行，不需要 Apple 设备保持在线。

一次部署连接一个 Apple 账户。这不是多用户日历服务。

部署前准备

你需要：

• 一个 Cloudflare 账户。

• 一个启用了双重认证的 Apple 账户。

• 一个支持远程 HTTPS 服务器和 OAuth 的 MCP 客户端。

• 你的 IANA 时区名称，例如 America/New_York。

自己打开 Apple 和 Cloudflare 的设置页面。Agent 可以指导你并验证结果，但它不应接收或输入你的密码。

[!WARNING] 切勿将你的 Apple 账户密码、Apple 应用程序专用密码或批准密码粘贴到聊天、源代码管理、日志或问题中。

Related MCP server: calendar-app-mcp

创建 Apple 应用程序专用密码

1. 打开 account.apple.com 并登录。

2. 选择 登录与安全 > 应用程序专用密码。

3. 选择 生成应用程序专用密码。

4. 给它一个清晰的标签，例如 Apple Calendar MCP。

5. 将生成的值保留在 Apple 页面上，直到 Cloudflare 要求提供为止。

Apple 要求应用程序专用密码启用双重认证。你最多可以有 25 个有效密码。你可以撤销其中一个或全部。更改或重置你的 Apple 主账户密码会撤销所有应用程序专用密码。请参阅 Apple 的应用程序专用密码说明。

[!WARNING] Apple 应用程序专用密码的权限范围比此 MCP 向客户端展示的日历权限更广。Worker 将自身限制为允许列表中的 iCloud CalDAV 主机，但 Apple 不会签发仅限日历的应用程序专用密码。

部署到 Cloudflare

1. 选择本页顶部的 Deploy to Cloudflare。

2. 登录 Cloudflare 并按照部署表单操作。

3. 当 Cloudflare 要求时输入三个机密值：

   • ICLOUD_USERNAME：用于你的 Apple 账户和 iCloud Calendar 的完整电子邮件地址。

   • ICLOUD_APP_PASSWORD：Apple 生成的应用程序专用密码。请原样保留。

   • APPROVAL_PASSWORD：一个单独的、唯一的密码，用于保护新的 MCP 客户端批准。不要重复使用任一 Apple 密码。

4. 等待 Worker 部署完成。

5. 打开 Workers & Pages，选择该 Worker，然后选择 Settings 并找到 Variables and Secrets。

6. 将 CALENDAR_TIME_ZONE 从 UTC 改为你的 IANA 时区名称，然后部署该设置。

7. 复制此形式的端点：https://<worker-name>.<account-subdomain>.workers.dev/mcp。

Cloudflare 将三个机密值存储为加密的 Worker 机密。部署表单不会将它们写入生成的仓库或本地的 .dev.vars 文件中。

如果你跳过了某个机密或需要替换，请打开 Workers & Pages，选择该 Worker，选择 Settings，找到 Variables and Secrets，将值作为 Secret 添加或编辑，然后选择 Deploy。

Cloudflare 会自动配置 OAUTH_KV 命名空间。不要在 wrangler.jsonc 中添加 KV ID。

连接 MCP 客户端

1. 将部署的 /mcp 端点添加为自定义远程 MCP 服务器或应用。

2. 选择 Connect。你的客户端应发现 OAuth 并打开 Apple Calendar MCP 批准页面。

3. 确认客户端名称和请求的权限。

4. 输入 APPROVAL_PASSWORD 并选择 Allow and return。如果页面要求超出你想要的访问权限，请选择 Cancel。

5. 等待客户端报告连接完成。如果浏览器标签页在完成后仍然打开，请关闭它。

6. 刷新或重新扫描客户端的工具。客户端可能在连接或服务器更新后缓存工具目录。

对于 Claude，请参阅 使用自定义连接器进行远程 MCP。对于 ChatGPT，请参阅 开发者模式和完整 MCP 连接器。

批准页面提供两种权限：

• 读取日历和事件 授予 calendar:read 并公开七个读取工具。

• 读取和编辑日历和事件 授予 calendar:read calendar:write 并添加四个变更工具。

更改权限需要重新授权并刷新工具目录。服务器更新不会向现有的只读授权添加写入工具。

[!WARNING] 涉及与会者或邀请的写入操作可能会向其他人发送电子邮件或通知。

验证连接

首先验证读取访问权限：

1. 调用 calendar_get_profile。确认 Apple 账户身份和时区。

2. 调用 calendar_list_calendars。确认预期的日历名称出现。

3. 如果你批准了只读访问，请确认客户端不显示变更工具。

部署、机密输入、OAuth 连接和成功的日历读取是各自独立的状态。成功的日历读取证明 Apple 凭据有效。

要验证写入访问权限，请先在 Apple Calendar 中创建一个空的临时日历。仅在你确认后，才让 Agent 运行此有界测试：

1. 创建一个具有唯一标题、无与会者、无重复、无提醒的未来事件。

2. 读取该事件并保留其当前 ETag。

3. 仅使用该 ETag 更改其标题。

4. 再次读取该事件，并使用返回的 ETag 删除它。

5. 确认该事件不存在。

如果清理失败，请记录确切的日历、标题和时间，以便你自己删除该事件。不要在你的默认日历上测试写入操作。

你也可以将这一有界流程提供给 Agent，见 使用 Agent 设置 Apple Calendar MCP。

工具

更新、删除和邀请响应工具需要最新的 ETag。重复事件发生的更改还需要搜索返回的原始 recurrenceId。

定时输入使用带 Z 或显式偏移量的 RFC 3339 时间戳。客户端可以省略 timeZone；创建时使用日历发布的 IANA 时区，然后使用 CALENDAR_TIME_ZONE。定时输出包含 UTC 和本地值。

location 是可见的日历字段。structuredLocation 可以添加标题、地址、纬度、经度和半径。验证过的坐标可启用 Apple Calendar 的地图预览。不要猜测坐标。

description 映射到日历备注。url 映射到事件 URL 字段。MCP 在不相关的更改期间保留不支持的附件和提醒类型，但它不会上传、下载或修改附件。它不导入原始 ICS。

使用自定义域名

默认的 workers.dev 端点不需要主机名配置。自定义域名需要一项显式的允许列表设置：

1. 在 Cloudflare 中打开该 Worker。

2. 选择 Settings > Domains & Routes > Add > Custom Domain 并添加主机名。

3. 在 Variables and Secrets 下，将 MCP_HOSTNAME 添加为纯文本变量。仅输入主机名，例如 calendar.example.com。不要包含 https://、路径、端口或凭据。

4. 部署该设置。

5. 在 https://<custom-host>/mcp 重新连接客户端，并重新完成授权。

主机名是 OAuth 身份的一部分。为 workers.dev 签发的令牌不会迁移到自定义源站。

添加 Cloudflare Access

内置的批准密码是默认的授权防护。Cloudflare Access 是可选的纵深防御。

如果你添加 Access，请仅保护 <hostname>/authorize。让 /mcp、/.well-known/*、/oauth/token 和 /oauth/register 可被 MCP 客户端访问。在验证 Access 保护 /authorize 之后，将 EXTERNAL_AUTHORIZATION=true 添加为纯文本 Worker 变量。

[!WARNING] 仅在外部防护保护 /authorize 后设置 EXTERNAL_AUTHORIZATION=true。该设置声明外部防护已生效。

安全性

Worker 在运行时接收你的 Apple 用户名和应用程序专用密码。你信任你的 Cloudflare 账户、部署的源代码、Apple 以及每个已连接的 MCP 客户端。限制对你 Cloudflare 账户的访问，并仅连接你信任的客户端。

APPROVAL_PASSWORD 保护新的批准。除非已配置此密码，或 EXTERNAL_AUTHORIZATION 声明了已验证的外部防护，否则批准路由会默认失败关闭。任何通过防护的人都可以针对配置的 Apple 账户授权客户端。

[!WARNING] 轮换 APPROVAL_PASSWORD 不会撤销已签发的 OAuth 令牌。

Cloudflare 的 OAuth 提供程序以哈希形式存储访问令牌、刷新令牌、授权码和已注册的客户端机密。它会加密授权属性。客户端名称和授予元数据在存储中仍然可见，因此它们不得包含机密。请参阅提供程序的 KV 存储和清理文档。

Worker 仅通过 HTTPS 将 Apple 凭据发送到允许列表中的 iCloud CalDAV 主机。工具参数不能选择上游主机。错误会隐去类似凭据的值。Worker 不会记录工具参数或事件负载。

工具结果可能包含标题、备注、位置、与会者和 URL。MCP 客户端可以根据自己的产品和工作区策略保留这些数据。

写入访问权限涵盖事件创建、更改、删除和邀请响应。ETag 可以防止覆盖较新的事件，但它们无法使无意的写入变得无害。不相关的更新会尽可能保留不支持的 Apple 属性。

从本规范仓库或你审查过更改的分支部署。远程 MCP 服务器可以在其所有者部署新代码时更改其工具目录。

撤销或轮换访问权限

如果你怀疑遭到入侵，请先撤销旧的 Apple 应用专用密码。然后替换它并验证访问。这会导致短暂中断。

故障排除

• 401 或 iCloud 密码被拒绝通常意味着应用专用密码缺失或被撤销。请在 Apple 和 Cloudflare 中创建或替换它。不要将其粘贴到聊天中。

• 缺少写入工具通常意味着客户端具有只读授权或缓存的工具目录。刷新工具，然后断开连接并在需要时重新授权。

• 拒绝 /mcp 的自定义域通常意味着 MCP_HOSTNAME 缺失或无效。设置准确的主机名并重新部署。

• 故障关闭的审批页面既没有 APPROVAL_PASSWORD，也没有声明的外部守卫。除非你已在 /authorize 上验证 Cloudflare Access，否则请添加审批密钥。

本地开发

bun install
cp .dev.vars.example .dev.vars
bun run test
bun run typecheck
bun run cloudflare:check

将 .dev.vars 保留在本地。使用 bun run deploy 部署。

许可证

MIT