iCloud

在这台电脑上运行 ›    为所有设备托管 ›    一键使用 Claude Desktop ›

向 AI 询问你这一周的安排、收件箱里的内容，或去年春天保存的文件，它都能立刻知道。
iCloud MCP 可将 Claude、Codex、ChatGPT 或任何其他 MCP 客户端连接到你日常使用的 Apple 账户。
它在你自己的设备上运行，密码也留在设备上，任何内容要离开设备前都会征求你的同意。

_{0.9 至 0.11 版：地图、信息、菜单栏应用和暂停功能、草稿和文件夹、日历和联系人群组，以及功能更丰富的提醒事项。0.6 至 0.8 版：日历速度提升约三倍、更轻量的邮件处理、首次调用即时完成、自定义规则文件、待回复事项、冲突检查，以及强化的重复规则防护。自 0.4 版起：支持撤销的批量清理、安全退订、精确预订、编辑备忘录、搜索 Drive 文件内容、生日和快捷指令。0.3 版：一键安装 Claude Desktop 扩展、本地模式、钥匙串存储、空闲时间、RSVP 和诈骗警告。}

邮件、日历和通讯录使用 Apple 的标准协议。
提醒事项、备忘录、iCloud Drive、地图、信息和健康数据通过 Mac 上的可选辅助程序处理。
它会向外连接，因此你的 Mac 无需开放端口。

已在 Claude（网页、桌面、手机、Claude Code 和桌面扩展）以及本地运行服务的 Codex CLI 上完成测试。任何支持 MCP 的客户端都能以相同方式运行：本地使用时由客户端自行启动服务，托管使用时则通过 OAuth 登录。

在本地运行

服务在你自己的电脑上运行。客户端需要时会启动服务并直接与之通信，因此无需公开地址、隧道、Docker 或 OAuth。网页和手机上的应用无法访问它；如需使用这些应用，请托管服务。

一键安装 Claude Desktop

1. 从最新版本下载 icloud-mcp-<version>.mcpb。
2. 双击该文件，或将其拖到 Claude Desktop → Settings → Extensions。
3. 填写你的 Apple Account 电子邮件地址、专用 App 密码（Claude Desktop 会将其保存在系统钥匙串中）、姓名和时区，例如 Europe/Amsterdam。

该服务默认要求先批准操作：邮件会保存到草稿，供你发送；向其他人发送邀请的功能则处于关闭状态。此设置适用于 Mail、Calendar 和 Contacts。Reminders、Notes 和 iCloud Drive 需要使用 Mac 辅助工具，并按照下方的手动设置进行配置。

手动设置（适用于任何 MCP 客户端）

1. 将设置放入只有你能读取的文件中。

mkdir -p ~/.icloud-mcp && chmod 700 ~/.icloud-mcp
cat > ~/.icloud-mcp/icloud.env <<'END'
[email protected]
ICLOUD_DISPLAY_NAME=Your Name
DEFAULT_TIMEZONE=Europe/Berlin
END
chmod 600 ~/.icloud-mcp/icloud.env

2. 将密码保存在 Keychain 中（Mac 上）。它会提示输入 App 专用密码，且不会在命令行中显示密码：

uvx icloud-mcp-server --store-password

不使用 Mac？改为在文件中添加 ICLOUD_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx。可以将配置中的任何设置放入文件；无需设置 MCP_PUBLIC_URL 和 MCP_OWNER_PASSWORD。

3. 将其添加到客户端（需要 uv）。

Claude Code：

claude mcp add icloud -- uvx icloud-mcp-server --local --env-file ~/.icloud-mcp/icloud.env

Codex：

codex mcp add icloud -- uvx icloud-mcp-server --local --env-file ~/.icloud-mcp/icloud.env

Claude Desktop：进入 Settings → Developer → Edit Config，在 claude_desktop_config.json 中添加以下内容，然后重启 Claude。Cursor（~/.cursor/mcp.json）、VS Code、Windsurf、Gemini CLI 和大多数其他客户端，都可以在各自的 MCP 设置中使用相同的 command 和 args：

{
  "mcpServers": {
    "icloud": {
      "command": "uvx",
      "args": ["icloud-mcp-server", "--local", "--env-file", "/Users/YOU/.icloud-mcp/icloud.env"]
    }
  }
}

如果客户端找不到 uvx，请使用其完整路径（which uvx）。如果没有 uv，请运行 pip install icloud-mcp-server，并将 icloud-mcp 用作命令。

提示

工具越少，选择越准。 客户端从较短的列表中更可靠地选择合适的工具。添加 TOOLS=essential，即可启用 19 个核心工具：搜索、读取和回复邮件；列出日程、查找空闲时间以及创建或更新日程；查找联系人；主要的提醒事项、备忘录和云盘工具；以及健康检查。按需添加具体名称，例如 TOOLS=essential,mail_move_messages，也可以选择整个类别：TOOLS=mail、TOOLS=mail,calendar（还包括 contacts、reminders、notes、drive、maps、imessage、health；健康检查始终保留）。

本地发送方式。 这里没有审批页面，因此默认设置 SEND_REQUIRES_APPROVAL=true 时，AI 发送的每条邮件都会改为保存到草稿文件夹中，结果也会说明这一点。你可以在 Mail 中检查邮件，然后自行点击 Send。设置 SEND_REQUIRES_APPROVAL=false 即可允许直接发送；此时只有客户端自身的审批提示会进行确认。

本地使用提醒事项、备忘录和 iCloud 云盘。 在环境变量文件中添加 ENABLE_REMINDERS=true（和／或 ENABLE_NOTES、ENABLE_DRIVE）以及 BRIDGE_TOKEN，启动一次客户端，然后安装 Mac 辅助程序，并设置服务地址 https://127.0.0.1:8001，以及从 ~/.icloud-mcp/bridge_fingerprint.txt 获取的指纹。在本地模式下，桥接服务只监听 127.0.0.1。如果两个客户端同时启动服务，只有先启动的客户端能使用 Mac 工具；Mail、Calendar 和 Contacts 在两个客户端中都可用。

快速开始

只需托管一次，你的 AI 就能通过网页、桌面应用和手机访问你的 iCloud：Claude、ChatGPT、Codex，或任何支持远程 MCP 服务的客户端。

你需要准备

• Docker 和 compose 插件（或 Python 3.11+）。
• 一个启用了双重认证的 Apple Account，以及一个专用 App 密码（account.apple.com → 登录与安全 → App 专用密码）。
• 一个公开的 HTTPS 地址。网页和手机应用从其服务提供商的云端连接，因此 LAN 或 VPN 地址无法使用。Cloudflare Tunnel 是最简单的方案：仅需出站连接，无需端口转发。
• 一个可以通过 OAuth 添加远程 MCP 服务的客户端，例如 Claude（自定义连接器）、ChatGPT（开发者模式）或 Codex。

警告

不要在服务前面设置 Cloudflare Access 或任何其他登录墙。客户端的服务器无法通过交互式登录，而且服务本身已有 OAuth。

1. 配置

git clone https://github.com/epinethrone/icloud-mcp.git && cd icloud-mcp
cp .env.example .env     # fill in ICLOUD_USERNAME, ICLOUD_APP_PASSWORD, ICLOUD_DISPLAY_NAME,
                         # MCP_PUBLIC_URL (your https address, no trailing slash), MCP_OWNER_PASSWORD
chmod 600 .env

MCP_OWNER_PASSWORD 是一个新生成的随机密码（至少 12 个字符），在批准客户端和访问发件箱页面时由你输入。它不是你的 Apple 密码。如果你更喜欢使用无回显提示，./configure.sh 会提示你输入密钥。

2. 在公开服务之前，使用真实的 iCloud 验证凭据

docker build -t icloud-mcp:local .
docker run --rm --env-file .env icloud-mcp:local python -m icloud_mcp.selftest                              # logs in to IMAP, SMTP, CalDAV, CardDAV; sends nothing
docker run --rm --env-file .env icloud-mcp:local python -m icloud_mcp.selftest --probe-sent [email protected]   # sends ONE test mail

如果登录失败，通常是登录名导致的：请分别设置 IMAP_USERNAME、SMTP_USERNAME、CALDAV_USERNAME 或 CARDDAV_USERNAME。

3. 运行

docker compose up -d --build     # listens on 127.0.0.1:8000 only

使用捆绑的 Cloudflare Tunnel：创建隧道，将其公开主机名（即 MCP_PUBLIC_URL 中的主机）指向 http://icloud-mcp:8000，将令牌写入 .tunnel.env，格式为 TUNNEL_TOKEN=...，然后运行 docker compose --profile tunnel up -d --build。任何 TLS 前端（Caddy、nginx）也都可用，只要它保留 Host 标头即可。MCP_PUBLIC_URL 必须与公开地址完全一致。

4. 连接客户端

将 https://<your-host>/mcp 添加为远程 MCP 服务。随后，服务会显示一个审批页面：输入所有者密码。

• Claude： 设置 → 连接器 → 添加自定义连接器。
• ChatGPT： 设置 → 应用与连接器 → 高级 → 开启开发者模式，然后创建使用 OAuth 的连接器（需要支持开发者模式的套餐）。
• Codex： codex mcp add icloud --url https://<your-host>/mcp，然后运行 codex mcp login icloud。
• 其他： 任何支持通过 OAuth 使用远程（可流式传输的 HTTP）MCP 服务的客户端。若网页客户端的登录流程会跳转回另一台主机，则需将该主机加入 OAUTH_ALLOWED_REDIRECT_HOSTS。

更改工具或设置后，请重新连接，因为客户端会缓存工具定义。菜单栏应用可以让一个或所有已连接的客户端退出登录；如果没有该应用，请删除数据卷中的 oauth_state.json 并重启，以撤销所有客户端的授权。

5. 检查是否正常运行

在新聊天中询问 “检查我的 iCloud 连接。” 你的 AI 会运行 icloud_check_health，登录每项服务并报告各自耗时。然后试着问 “我这周的日历上有什么？” 并让它给你发邮件。使用默认设置时，不会发送任何内容：消息会留在 https://<your-host>/dashboard/approvals，直到你批准为止。如果遇到问题，请参阅故障排除。

审批外发邮件

默认启用 SEND_REQUIRES_APPROVAL=true 时，mail_send_message、mail_reply_to_message 和 mail_forward_message 会返回 queued_for_owner_approval，不会发送任何内容。打开 https://<your-host>/dashboard/approvals（将其加入书签，并且只在此处登录，切勿通过 Agent 提供的链接登录），检查确切的收件人和正文，然后批准或丢弃。排队的消息会在 OUTBOX_TTL_SECONDS 指定的时间后过期（默认 24 小时），且最多只会释放一次。旧版 https://<your-host>/outbox 页面仍可使用，每次访问时都会要求输入所有者密码。

控制面板

https://<your-host>/dashboard 是管理服务器的地方：查看哪些请求在等待你批准、Agent 做了哪些更改、连接了哪些应用，以及邮件、日历和联系人是否能正常响应。手机上使用时显示标签栏，电脑上使用时显示侧边栏，并支持浅色和深色模式。

• 使用通行密钥登录。 先使用所有者密码登录一次，然后在“安全”下添加通行密钥：之后即可使用 Face ID、Touch ID 或安全密钥登录。通行密钥只能用于服务器自己的地址，因此外观相似的页面无法使用它。添加通行密钥后，设置 OWNER_PASSWORD_LOGIN=false 即可关闭密码登录。通行密钥需要安装可选的 webauthn 软件包（pip install "icloud-mcp-server[passkey]"）；Docker 镜像已包含该软件包。
• 活动记录。 Agent 执行的每项写入操作（移动邮件、更改日历事件、编辑联系人）、每次批准和丢弃、每次登录和失败的尝试，以及每次连接或退出的应用，都会记录到 DATA_DIR/audit.jsonl，其中包含名称、地址和主题，但绝不包含邮件正文、密码或令牌。每条记录都包含上一条记录的哈希值；“活动”页面会显示文件之后是否被更改。记录保留 AUDIT_KEEP_DAYS（90）天。设置 AUDIT_LOG=false 可关闭此功能。
• 日历邀请也可以等待你处理。 设置 ALLOW_CALENDAR_INVITES=approve 后，任何会让 iCloud 给其他人发送邮件的日历更改（创建、修改或取消含受邀者的事件，或回复邀请）都会暂存在“审批”页面，而不会立即写入。批准后只会写入你看到的内容，且仅当事件自此之后未发生变化时才会写入；否则不会写入，页面也会说明原因。将事件移至其他日历不会发送邮件，也不会暂存。
• 设置。 服务器的所有行为都可以在“设置”中更改，包括区域和工具、邮件发送方式、邀请、联系人、Mac 助手、只读模式以及控制面板本身。来自环境变量的值会在对应字段标明；在此设置的值会列出，并附有“重置”按钮。更改会保存到 DATA_DIR/settings.json，优先于环境变量，并在重启后生效（可通过一个按钮重启）。服务器会先检查新值能否使其正常启动，再保存更改；如果更改会降低防护级别，则会要求你重新登录。服务器的监听地址、应用的登录方式以及连接目标仍由环境变量控制，页面仅显示这些信息。DASHBOARD_SETTINGS=view 会显示设置但不允许更改；off 会忽略 settings.json。
• 实时更新，支持安装。 打开的“概览”或“审批”页面会在 15 秒内显示新请求，无需重新加载；“发送”和“丢弃”可直接在页面中操作：你可以在“概览”中打开请求，并在对应行中批准；丢弃操作可在五秒内撤销。页面检查更新不会计作使用，因此打开的标签页仍会在 DASHBOARD_SESSION_MINUTES 设定的时间后退出。在 Chrome 和 Edge 中，或在 Safari 中使用“添加到主屏幕”，即可将控制面板安装为应用。它的 Service Worker 不会缓存任何内容，因此邮件不会存储在浏览器中。
• 会话。 登录后，若连续 DASHBOARD_SESSION_MINUTES（30）分钟未使用，会话即过期，最长不超过 12 小时。如果登录已超过五分钟，移除通行密钥、更改密码和退出应用时都需要确认。
• 登录记录清晰易读，通行密钥登录也不会受影响。 锁定机制拦截的登录失败会在十分钟窗口结束时写入一条汇总记录，即使之后没有其他活动也会如此，因此活动日志能够显示每次失败集中出现的情况，同时避免记录泛滥。登录凭证由每个进程独有的密钥签名，且绝不会存储。只有使用通行密钥成功登录后，凭证才会计为已使用，因此大量挑战请求既不会填满任何存储空间，也不会影响所有者使用通行密钥登录。服务器重启后，未完成的登录凭证会失效；所有者只需重新登录。

安全

能够读取邮件并代你执行操作的连接器是提示词注入的攻击目标：恶意邮件或邀请可能包含试图操控 Agent 的文本。服务会将此类内容标记为不可信，并告知 Agent 应将其视为数据，但这只是对大模型的请求，并非保证。真正能保护你的是配置：

大多数客户端也可以在工具运行前征求你的许可（在 Claude 中，可为每个工具启用“使用前询问”）：请将此设置用于发送、回复、转发和删除工具。任何获得应用专用密码的人都拥有对邮件、日历和联系人的完全访问权限（Apple 不提供范围更窄的权限），因此请妥善保护服务及其 .env。

工具

92 个工具。 其中 50 个用于 Mail、Calendar、Contacts、时钟和运行状况检查；可选 Mac 辅助程序另提供 40 个；还有 2 个用于你允许名单中的 Shortcuts。打开相应部分查看详情。

每个名称的格式为 area_verb_noun（mail_send_message、calendar_create_event）。11 个工具在 0.7.0 中重命名，36 个工具在 0.12.0 中重命名（例如 mail_send 这样有动词但没有名词的名称），以符合该格式；TOOLS 仍接受旧名称，并会记录新名称。

服务器还提供 MCP 提示词，客户端可将其显示为一键工作流：整理我的收件箱、我欠下的回复、我正在等待的后续回复、规划我的一周、为预约做准备、根据邮件创建日历、找个时间和某人见面、整理我的提醒事项和即将到来的生日。只有启用了所需功能区域时，相应工作流才会显示；每个工作流都会要求 Agent 在发送、预订、移动或删除任何内容之前，先向你展示计划执行的操作。

与 Agent 协作

服务器会告知每个 Agent 如何使用它：服务器的说明根据你实际启用的工具生成，始终以安全规则开头（邮件、日历事件和联系人中的内容均为不可信数据，绝不是指令），并说明你配置的审批流程。

使用 AGENT_NOTES_FILE 添加自己的规则：在服务器所在机器上的简短 Markdown 文件，每次使用时都会重新读取，因此编辑后无需重新连接即可生效。Agent 会在安全规则之后看到这些内容；这些规则可以补充安全规则，但绝不能放宽限制。Agent 也可以将其作为 icloud://agent-notes 资源重新读取。docs/agent-notes.example.md 展示了具体思路：哪个日历用于什么、如何为邮件签名、哪些列表是共享的。请将文件控制在 8,000 个字符以内。

以下工具可减少 Agent 的猜测：

• icloud_get_time 提供所有者的日期、时间和时区，因此“明天”会对应正确的日期。
• mail_list_awaiting_reply 列出你发出但尚未收到回复的邮件；使用带有 unanswered_only 和 people_only 的 mail_search_messages，可以查找你仍欠下回复的邮件，同时排除新闻邮件。
• calendar_create_event 会报告时间重叠的日历事件和可能的重复事件，并可拒绝创建其中任一类；使用带有 needs_reply 的 calendar_list_events 可查找仍在等待回复的邀请。
• OWNER_ADDRESSES 列出你的别名，因此发送到这些别名的邀请也会计入你的邀请。

工具较多时，有些客户端的选择会不太可靠：TOOLS=essential 会加载较小的核心工具集，而 TOOLS=mail,calendar 会加载完整的对应功能区域。

性能

在本地测试环境中测得，每次往返额外增加 40 ms，对比 0.5.0 和 0.6.0 （详情和方法）：

连接会在最后一次调用后保持登录 10 分钟（IMAP_IDLE_SECONDS、CALDAV_KEEPALIVE_SECONDS），而 WARMUP_ON_START 会在服务器启动时登录。dev/bench.py 可使用你自己的账户重复这些测量。

从菜单栏控制

menubar/ 包含 iCloud MCP Control，这是一款原生 macOS 应用，用于在 Mac 上运行的服务器。它的菜单是标准 macOS 菜单，类似 Time Machine：显示服务器是否正在运行、拥有多少工具和已连接应用，以及用通俗文字说明任何问题；你还可以暂停服务器（工具会回复服务器已暂停，但不会断开任何连接）、重启或停止服务器、Mac 助手和隧道。其设置可更改所有者密码、替换 iCloud 专用应用密码（保存前会先通过 iCloud 测试），并列出每个已连接的应用及其上次使用时间，让你可以退出一个、多个或全部应用的登录。使用 ADMIN_PORT 开启其管理 API：它仅在 127.0.0.1 上通过自己的端口监听，每个请求都需要服务器写入数据文件夹中 admin-token 的令牌。

通过你的 Mac 使用提醒事项、备忘录、iCloud 云盘、地图、信息和健康

Apple 只在自家设备上提供提醒事项、备忘录、iCloud 云盘、Apple 地图、你的信息历史记录和健康数据，因此需要在你的 Mac 上运行一个小型辅助程序（mac-helper/），在服务发出请求时执行相应操作。

• 你的 Mac 上不会有任何程序监听。 辅助程序会主动连接到服务的专用 HTTPS 端口（绝不会连接到公共地址，也不会经过隧道），并长轮询以获取任务。
• 绝不会发送代码。 服务只会发送操作名称，以及来自固定列表、经过验证的参数。提醒事项会运行安装程序在你的 Mac 上构建的小型 EventKit 程序，地图会运行小型 MapKit 程序。备忘录会运行静态脚本。信息会以只读方式读取你自己的信息数据库。iCloud 云盘和健康各自会通过 Apple 自带的 Python 运行一个固定的 Python 脚本。无论哪种情况，参数都以单个 JSON 值的形式传入，绝不会作为代码传入。
• 已固定并经过身份验证。 使用通过指纹固定的自签名证书进行 TLS 验证，并使用 Bearer 令牌。
• 关闭时如实反馈。 你的 Mac 开机且可连接时（通过家庭网络或 VPN），辅助程序即可工作。否则，工具会说明情况。

在 .env 中启用此功能：设置 ENABLE_REMINDERS=true、ENABLE_NOTES=true、ENABLE_DRIVE=true、ENABLE_MAPS=true、ENABLE_IMESSAGE=true 和 ENABLE_HEALTH=true 中任意一项，设置至少包含 32 个随机字符的 BRIDGE_TOKEN，并将 BRIDGE_BIND 设置为 Mac 可连接到服务的地址。服务会在日志中输出供安装程序使用的证书指纹，并将其写入数据文件夹中的 bridge_fingerprint.txt。然后按照 Mac 辅助程序指南操作。

快捷指令，双重允许列表。 若要让助手运行你的一些快捷指令（shortcuts_list_shortcuts、shortcuts_run_shortcut），请在服务端的 SHORTCUTS_ALLOW 中列出快捷指令的准确名称，并且在 Mac 上的 ~/Library/Application Support/icloud-mac-helper/shortcuts-allow.txt 中每行列出一个名称。名称必须同时出现在两个列表中，因此即使服务遭到入侵，也无法运行你未在 Mac 本机允许的快捷指令。Apple 的 shortcuts 命令会运行该快捷指令，并可选地接收文本输入，之后会返回其文本输出。未设置允许列表或服务为只读时，这些工具不会生效。

重要

iCloud 云盘和信息需要为辅助程序使用的 Python 授予“完全磁盘访问权限”。 在 macOS 27 上，只有辅助程序以命令行工具中的 Python.app 可执行文件运行时，授权才会生效；安装程序会完成相应设置。详情请参阅 Mac 辅助程序指南。

配置

所有设置都是环境变量。.env.example 为每个设置都附有注释。

故障排查

先让 AI “检查我的 iCloud 连接”：icloud_check_health 会测试所有已启用的区域，并指出失败的区域。

欢迎提交问题和拉取请求。每个拉取请求都会针对 Python 3.11 至 3.13 运行离线测试，并接受自动化的安全审查。

• 安全问题： 请不要公开提交问题。请改为遵循安全政策。
• 提交拉取请求前： 确保 pytest tests --ignore=tests/integration 通过，并为新行为添加测试。
• 任何与 iCloud 通信的内容： 运行 selftest，并使用真实账户手动测试。iCloud 不接受的操作，本地测试服务可能会接受。
• 新工具： 保持现有的安全默认设置。任何发送、邀请或删除操作都必须继续受现有设置限制；从 iCloud 读取的任何内容都必须视为数据，而不是指令。

python -m venv .venv && . .venv/bin/activate
pip install -e ".[test]"
pytest tests --ignore=tests/integration      # offline tests, no network
sudo apt install dovecot-imapd && dev/start_local_stack.sh
pytest tests                                 # adds integration tests against local Dovecot, an SMTP sink and Radicale
python packaging/mcpb/build.py               # builds the Claude Desktop extension into dist/
python dev/readme_art.py                     # redraws the README artwork in assets/readme/

致谢

本项目基于 MCP Python SDK、IMAPClient、caldav、icalendar、html2text、python-dateutil、Uvicorn 和 HTTPX 构建。Notes 脚本改编自 MrGo2/icloud-mcp（MIT）；请参阅 THIRD_PARTY_NOTICES.md。