iCloud MCP

icloud-mcp 涵盖七项 Apple 服务，支持两种可互换的后端；据我们所知，它是唯一做到这一点的 MCP 服务。本地模式通过 AppleScript 驱动 macOS 原生应用：无需凭据、无需网络，还能访问 iCloud 协议未开放的服务（提醒事项、备忘录、信息、Safari）。云端模式则改用 IMAP/SMTP、CalDAV 和 CardDAV，因此可在任何设备上运行，不限于 Mac。set-mode 工具可在运行时切换两种模式，无需重启。

功能

该服务提供 41 个工具，涵盖邮件、日历、通讯录、提醒事项、备忘录、信息和 Safari。每个工具都有类型化的架构、人类可读的标题和行为注释，并且每个 list-* 工具都会在文本输出之外返回机器可读的 structuredContent。本地模式完全无需密码；macOS 自动化权限取而代之。

访问与安全模型

该服务仅通过 stdin/stdout 使用 JSON-RPC 通信。它不会开放端口，也不会监听套接字。

凭据绝不会被记录到日志中。ICLOUD_APP_PASSWORD 在启动时读取一次，仅交给 IMAP/SMTP/CalDAV/CardDAV 客户端；诊断信息只会显示固定的掩码，不会显示实际值。密码的存放位置由你决定：手动安装时，可将其放在模块旁边的 .env 文件中；也可使用 .mcpb 包的敏感字段，由宿主存储在 macOS 钥匙串中。本地模式不需要任何密码，因为 macOS 会通过各应用自身的自动化权限提示控制访问，而且你可以随时撤销这些权限。

每个工具参数都会在处理程序运行前通过 zod 架构验证。参数在每个 AppleScript 插值位置也会进行强制转换，因此非数字值无法传入脚本模板。

隐私政策

该服务不收集也不留存任何信息：没有遥测、没有分析，也不会在磁盘上保存状态。你的数据只会在你的设备、你连接的 AI 客户端和 Apple 服务之间传输。完整政策涵盖数据收集、存储、第三方共享、保留期限和联系信息，详见 PRIVACY.md。

工具

标记为仅限本地的工具在云端模式下会返回错误，因为 iCloud 协议不提供这些服务。

身份验证

• about
  • 返回有关此服务、当前模式以及是否已配置凭据的信息
  • 无输入
• check-auth-status
  • 验证凭据是否可用于当前模式
  • 无输入
• set-mode
  • 在本地和云端模式之间切换，无需重启
  • 输入：mode（字符串，local 或 cloud）

电子邮件

• list-emails：folder（字符串，可选），count（数字，可选，最大值为 50）
• read-email：uid（字符串），folder（字符串，可选）
• send-email：to、subject、body（字符串）；cc、bcc（字符串，可选）；isHtml（布尔值，可选，仅限云端模式）
• search-emails：query、from、subject、folder（字符串，可选），unreadOnly（布尔值，可选），count（数字，可选）
• mark-as-read：uid（字符串），folder（字符串，可选），isRead（布尔值，可选）
• list-folders：无输入

日历

• list-events：count（数字，可选，最大值为 50），daysAhead（数字，可选）
• create-event：summary、start、end（字符串，ISO 8601）；description、location（可选）；calendarUrl（云端）或 calendarName（本地）
• update-event：eventUrl（字符串）；summary、start、end、description、location 中的任意字段。只会更改你传入的字段
• delete-event：eventUrl（字符串）
• list-calendars：无输入

联系人

• list-contacts：count（数字，可选，最大值为 50）
• search-contacts：query（字符串），count（数字，可选）。匹配姓名、组织、电子邮件和电话；匹配电话时会忽略格式
• read-contact：contactUrl（字符串）
• create-contact：displayName、firstName、lastName、email、phone、organization、title、notes（均为可选）
• delete-contact：contactUrl（字符串）
• list-contact-accounts：无输入（仅限本地）
• list-contact-groups：accountId（字符串，可选）（仅限本地）

提醒事项（仅限本地）

• list-reminder-lists：无输入
• list-reminders：listName（字符串，可选），includeCompleted（布尔值，可选），count（数字，可选）
• create-reminder：name（字符串）；body、dueDate、listName（可选）；priority（数字 0-9，可选）
• update-reminder：reminderId（字符串）；name、body、dueDate、priority 中的任意字段
• complete-reminder：reminderId（字符串），completed（布尔值，可选）
• delete-reminder：reminderId（字符串）
• search-reminders：query（字符串），count（数字，可选）

备忘录（仅限本地）

• list-note-folders：无输入
• list-notes：folderName（字符串，可选），count（数字，可选）
• read-note：noteId（字符串）
• create-note：title（字符串），body（字符串，可选），folderName（字符串，可选）
• search-notes：query（字符串），count（数字，可选）

信息（仅限本地）

读取信息需要 imsg CLI 和“完全磁盘访问”权限。

• list-chats：limit（数字，可选）
• read-messages：chatId（数字）；limit（数字，可选）；start、end（ISO 8601，可选）；attachments（布尔值，可选）
• send-message：to（字符串），body（字符串），file（字符串，可选）
• react-message：chatId（数字），type（love、like、dislike、laugh、emphasis、question）

Safari（仅限本地）

• list-safari-tabs：无输入
• get-current-safari-url：无输入
• open-safari-url：url（字符串），inNewWindow（布尔值，可选）
• close-safari-tab：windowIndex（数字，可选），tabIndex（数字，可选）

工具注解（MCP 提示）

每个工具都会明确声明其行为，而不依赖规范中刻意偏保守的默认值。所有 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：所有 Email 和 Calendar 工具、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 中：

Install the iCloud MCP server. It is the npm package "mcp-icloud" (Node 20+),
stdio transport, server name "icloud", command "npx" with args ["-y", "mcp-icloud"].
On Claude Code run: claude mcp add --transport stdio icloud -- npx -y mcp-icloud
For other clients, add that command/args pair to the client's MCP config file.
Local mode (default) needs macOS; cloud mode needs env vars USE_LOCAL_MODE=false,
ICLOUD_EMAIL and ICLOUD_APP_PASSWORD (app-specific password from account.apple.com).
Docs: https://github.com/MrGo2/icloud-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"]
    }
  }
}

若使用云端模式，请添加凭据：

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"],
      "env": {
        "USE_LOCAL_MODE": "false",
        "ICLOUD_EMAIL": "[email protected]",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio icloud -- npx -y mcp-icloud

VS Code

使用本 README 顶部的徽章，或将相同的 command/args 对添加到 MCP 设置中。

桌面扩展（.mcpb）

从 Releases 下载 .mcpb 并打开，以侧载安装。该安装包会提示你选择模式；若使用云端模式，它会将应用专用密码存储在 macOS 钥匙串中，而不是文件里。

权限与故障排除

macOS 自动化提示（本地模式）

工具首次访问某个应用时，macOS 会询问是否允许发起调用的程序控制该应用。每个应用只会询问一次，而不是每个工具询问一次。请批准提示，或稍后前往 System Settings → Privacy & Security → Automation 授予权限。

如果你关闭了提示，对该应用的调用会因授权错误而失败（osascript 错误 -1743，"not authorized to send Apple events"）。macOS 不会自行再次询问。请在“自动化”中重新启用复选框，或重置权限决定：

tccutil reset AppleEvents

这会清除所有应用的自动化权限，因此下次使用时会再次出现提示。

完全磁盘访问权限（读取信息）

list-chats 和 read-messages 通过 imsg CLI 读取 Messages 数据库；此操作受完全磁盘访问权限控制，而非自动化权限控制。请前往 System Settings → Privacy & Security → Full Disk Access，为启动服务的程序（Claude Desktop、终端或编辑器）授予权限。若未授予权限，这些工具会提示需要完全磁盘访问权限。

如果 imsg 安装在特殊位置，请明确指定其路径：

export ICLOUD_MCP_IMSG_PATH=/opt/homebrew/bin/imsg

否则，服务会依次检查 ICLOUD_MCP_IMSG_PATH、IMSG_PATH、两个 Homebrew 前缀，最后检查 PATH。

已知限制：大型邮箱

Mail.app 工具通过 AppleScript 遍历邮件；对于非常大的邮箱，这种方式速度较慢，并且可能在返回结果前超出 Apple Event 超时限制。请使用 folder 缩小查询范围并设置较小的 count，或使用云端模式，由 IMAP 在服务端进行筛选。此限制源于 AppleScript 桥接机制，服务本身无法规避。

已知限制：大型日历数据集

本地模式下的 list-events 也受同样的 AppleScript 限制。日期范围已通过 whose 查询在 Calendar.app 内筛选，但对于日历数量较多的账户，尤其是包含多年活动的订阅日历（节假日、体育赛事、旅行信息源），查询仍可能超出任何合理的超时限制。list-calendars 和事件写入工具不受影响。在计划中的 EventKit 后端上线之前（参见 #10），请使用云端模式读取事件：CalDAV 会在服务端进行筛选，并且无论数据规模大小都能快速完成。

App 专用密码（云模式）

云模式需要 App 专用密码。你的常规 Apple ID 密码无法使用，而且只有开启了双重认证的账户才能向 Apple 申请 App 专用密码。

1. 在 appleid.apple.com 登录。
2. 前往 登录与安全 → App 专用密码。
3. 生成一个密码并为其命名，例如“iCloud MCP”。
4. 将它与 ICLOUD_EMAIL 一起填入 ICLOUD_APP_PASSWORD。

如果密码泄露，可在同一页面撤销。

查看服务端的判断结果

调用 about 查看当前模式和服务列表，并调用 check-auth-status 确认凭据在当前模式下可用。

要求

• Node.js 20 或更高版本
• 本地模式：安装了相关应用的 macOS，以及 imsg；如果要读取信息，还需要“完全磁盘访问权限”
• 云模式：任何操作系统、已开启双重认证的 iCloud 账户，以及 App 专用密码。仅支持邮件、日历和通讯录

配置

变量	默认值	用途
USE_LOCAL_MODE	true	false 表示选择云模式
ICLOUD_EMAIL	（未设置）	iCloud 地址，仅用于云模式
ICLOUD_APP_PASSWORD	（未设置）	App 专用密码，仅用于云模式
ICLOUD_MCP_IMSG_PATH	（未设置）	imsg 二进制文件的显式路径

从环境变量或模块旁的 .env 文件读取。参见 .env.example。

开发

pnpm 是受支持的包管理器；提交的锁定文件为 pnpm-lock.yaml。

pnpm install
pnpm test          # unit + contract suites, and a live stdio session
pnpm run inspect   # drive the server with the MCP Inspector

测试套件会对 osascript 和 imsg CLI 进行桩替换，因此不会接触真实的邮件、日历或信息数据，并且可在任何操作系统上运行。

许可证

MIT。参见 LICENSE。