用途
icloud-mcp 是一个 MCP（Model Context Protocol）服务器，用于让 AI 客户端访问 Apple 服务。它覆盖七项服务：Mail（邮件）、Calendar（日历）、Contacts（通讯录）、Reminders（提醒事项）、Notes（备忘录）、Messages（信息）和 Safari。据项目说明，它是目前唯一同时覆盖这七项服务并提供两种可互换后端的 MCP 服务器。
两种后端模式
本地模式：通过 AppleScript 驱动 macOS 原生应用。无需凭据、不联网，可访问 iCloud 协议未暴露的服务（提醒事项、备忘录、信息、Safari）。
云端模式：使用 IMAP/SMTP、CalDAV 和 CardDAV 协议，可在任意机器上运行，不限于 Mac。仅覆盖邮件、日历和通讯录。
set-mode 工具可在运行时切换两种模式，无需重启。
主要能力
服务器共暴露 41 个工具，按服务划分：
- 通用：
about（返回服务器信息、当前模式、凭据配置状态）、check-auth-status（验证当前模式凭据可用性）、set-mode（切换 local/cloud）。 - 邮件：
list-emails、read-email、send-email、search-emails、mark-as-read、list-folders。 - 日历：
list-events、create-event、update-event、delete-event、list-calendars。 - 通讯录：
list-contacts、search-contacts、read-contact、create-contact、delete-contact、list-contact-accounts（仅本地）、list-contact-groups（仅本地）。 - 提醒事项（仅本地）：
list-reminder-lists、list-reminders、create-reminder、update-reminder、complete-reminder、delete-reminder、search-reminders。 - 备忘录（仅本地）：
list-note-folders、list-notes、read-note、create-note、search-notes。 - 信息（仅本地）：
list-chats、read-messages、send-message、react-message。读取需要 imsg CLI 和完全磁盘访问权限。 - Safari（仅本地）：
list-safari-tabs、get-current-safari-url、open-safari-url、close-safari-tab。
每个工具都带有类型化 schema、人类可读标题和行为注解。所有 list-* 工具在文本输出之外还返回机器可读的 structuredContent。标记为“仅本地”的工具在云端模式下会返回错误，因为 iCloud 协议不暴露这些服务。
访问与安全模型
- 服务器仅通过 stdin/stdout 进行 JSON-RPC 通信，不开放端口、不监听套接字。
- 凭据从不记录日志。
ICLOUD_APP_PASSWORD在启动时读取一次，仅传递给 IMAP/SMTP/CalDAV/CardDAV 客户端；诊断信息只打印固定掩码。密码可放在模块旁的.env文件，或.mcpb包的敏感字段（由宿主存入 macOS 钥匙串）。本地模式无任何密码，macOS 通过各应用的自动化授权提示控制访问，可随时撤销。 - 每个工具参数在执行前都经过 zod schema 校验，并在 AppleScript 插值处进行类型强制转换。
- 服务器不收集、不保留任何数据：无遥测、无分析、无磁盘状态。数据仅在用户机器、所连接的 AI 客户端和 Apple 服务之间流动。完整政策见 PRIVACY.md。
工具行为注解
所有 list-*、read-*、search-*、get-* 工具以及 about、check-auth-status 标记为只读。九个工具带 destructiveHint：四个删除操作（delete-event、delete-contact、delete-reminder、close-safari-tab）、三个不可逆触达他人的操作（send-email、send-message、react-message）以及两个原地更新（update-event、update-reminder）。触达网络或他人的工具带 openWorldHint：所有邮件和日历工具、send-message、react-message、open-safari-url。只读工具加上 mark-as-read、complete-reminder、update-reminder、update-event、set-mode 标记为幂等。
使用方式
需要 Node.js 20 或更高版本。
安装方式包括：
- 让 AI 客户端（Claude、Claude Code、Cursor、ChatGPT 或任何有 shell/配置访问权限的 agent）自动安装。
- 添加到
claude_desktop_config.json。 - 云端模式需添加凭据。
- 桌面扩展（.mcpb）：从 Releases 下载
.mcpb并打开侧载。该包会提示选择模式，云端模式下将应用专用密码存入 macOS 钥匙串而非文件。
包管理器支持 pnpm，仓库提交了 pnpm-lock.yaml。
权限与故障排查
macOS 自动化提示（本地模式）：工具首次访问某应用时，macOS 会询问是否允许调用程序控制它。每个应用只询问一次，而非每个工具一次。可在“系统设置 → 隐私与安全性 → 自动化”中批准或稍后授予。若忽略提示，对该应用的调用会失败并报授权错误（osascript error -1743）。macOS 不会自行再次询问，需重新勾选或重置决定（重置会清除所有应用的自动化权限）。
完全磁盘访问（读取信息）：list-chats 和 read-messages 通过 imsg CLI 读取信息数据库，受完全磁盘访问而非自动化控制。需在“系统设置 → 隐私与安全性 → 完全磁盘访问”中授予启动服务器的程序（Claude Desktop、终端或编辑器）。若 imsg 安装在非常规位置，可显式指定路径；服务器会依次查找 ICLOUD_MCP_IMSG_PATH、IMSG_PATH、两个 Homebrew 前缀，最后是 PATH。
已知限制
- 大型邮箱：Mail.app 工具通过 AppleScript 遍历消息，在超大邮箱上很慢，可能在返回前超出 Apple Event 超时。可用 folder 和较小的 count 缩小请求，或改用云端模式（IMAP 在服务端过滤）。这是 AppleScript 桥接的固有属性。
- 大型日历集：本地模式的
list-events有同样的 AppleScript 瓶颈。日期窗口已在 Calendar.app 内用 whose 查询过滤，但在日历众多（尤其是订阅了多年事件如节假日、体育赛事、旅行源）的账户上仍可能超时。list-calendars和事件写入工具不受影响。在计划中的 EventKit 后端落地前，读取事件建议使用云端模式（CalDAV 服务端过滤，任意规模都很快）。
云端模式的应用专用密码
云端模式需要应用专用密码。普通 Apple ID 密码无效，且 Apple 仅对开启双重认证的账户发放应用专用密码。步骤：登录 appleid.apple.com；进入“登录与安全 → 应用专用密码”；生成并命名（如“iCloud MCP”）；将其与 ICLOUD_EMAIL 一起放入 ICLOUD_APP_PASSWORD；若泄露可在同一页面撤销。
环境要求
- Node.js 20 或更高版本。
- 本地模式：macOS 及安装相关应用；如需读取信息，还需 imsg 和完全磁盘访问。
- 云端模式：任意操作系统、开启双重认证的 iCloud 账户、应用专用密码。仅覆盖邮件、日历和通讯录。
环境变量从环境或模块旁的 .env 文件读取，参见 .env.example。测试套件对 osascript 和 imsg CLI 打桩，不接触真实邮件、日历或信息数据，可在任意操作系统运行。
许可
MIT，见 LICENSE。
