icloud-mcp

icloud-mcp

一个 Model Context Protocol 服务，通过 IMAP 和 CalDAV 为 AI 助手提供对 iCloud 邮件和日历的只读访问权限。凭据保存在操作系统的钥匙串中（默认使用 macOS Keychain），绝不会存储在配置文件或代码仓库中。

默认配置面向 iCloud，但所有端点均可覆盖，因此也适用于任何标准 IMAP/CalDAV 提供商。

状态

默认只读；写入功能必须明确选择启用。 邮件、日历和通讯录都可以列出、搜索和读取，但无法进行任何更改：IMAP 连接以只读模式打开，并使用 BODY.PEEK[] 获取正文，因此邮件甚至不会被标记为已读。

变更类工具涵盖邮件（send_mail、reply_mail、forward_mail）、日历（create_event、update_event、delete_event）和通讯录（create_contact、update_contact、delete_contact）——但除非设置 ICLOUD_ENABLE_WRITES=1，否则这些工具全部禁用；即使启用，每次写入操作也都必须先进行交互式确认（MCP elicitation）。请参阅写入（选择启用）。

写入（选择启用）

变更操作通过两种方式进行限制：

1. 操作员开关 — 除非在服务的环境中设置了 ICLOUD_ENABLE_WRITES=1，否则写入工具会拒绝执行并返回说明性错误。
2. 逐项操作确认 — 启用后，每个写入工具都会回调客户端，要求其在执行前确认具体操作。破坏性操作（删除事件/通讯录）也采用相同的限制方式——无需额外的强制标志，只需进行同样的确认。

iCloud 会提供一个适用于 IMAP、SMTP、CalDAV 和 CardDAV 的单一 App 专用密码——没有按权限限定的“仅写入”凭据——因此，写入安全性由结构设计保障：邮件通过单独的新 SMTP 连接发送（读取路径中的 IMAP 客户端不具备发送能力），并且所有变更操作都受到选择启用标志和确认机制的保护。

安装

pip install icloud-mcp

也可以不安装而直接运行——适用于按需启动服务的 MCP 客户端：

uvx icloud-mcp

要直接从 GitHub 安装最新的未发布代码：

pip install git+https://github.com/eodozzy/icloud-mcp

或者用于本地开发：

git clone [email protected]:eodozzy/icloud-mcp
cd icloud-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[test]"

需要 Python 3.11+。

凭据

为你的 Apple ID 生成一个 App 专用密码（切勿使用主密码），然后将其存入钥匙串：

# macOS
security add-generic-password -a "[email protected]" -s "icloud-mcp" -w "xxxx-xxxx-xxxx-xxxx"

在其他平台上，使用跨平台的 keyring 库——keyring set icloud-mcp [email protected] 也可以在任何平台上使用。

用户名来自 ICLOUD_USERNAME 环境变量。密码的解析顺序如下：

1. 操作系统钥匙串（ICLOUD_KEYRING_SERVICE，默认值为 icloud-mcp，以及用户名）
2. ICLOUD_APP_PASSWORD 环境变量（后备方案）

要复用现有的钥匙串条目（例如名为 my-icloud 的条目），请设置 ICLOUD_KEYRING_SERVICE=my-icloud。

配置

设置 ICLOUD_USERNAME（必填）。其他配置均为可选——完整的端点/时区覆盖列表请参阅 .env.example。

注册到 MCP 客户端

该服务通过 stdio 使用 MCP：客户端会将 icloud-mcp 命令作为子进程启动，并通过 stdin/stdout 与其通信。将其“安装”到客户端，只需告知客户端要运行的命令以及要传递的环境变量——密码本身仍保存在钥匙串中，绝不会存储在客户端配置中。

如果 icloud-mcp 不在你的 PATH 中（例如你将其安装到了虚拟环境中），请使用启动器的绝对路径，例如 /path/to/repo/.venv/bin/icloud-mcp。

Claude Code

claude mcp add icloud \
  --env [email protected] \
  --env ICLOUD_KEYRING_SERVICE=icloud-mcp \
  -- icloud-mcp

然后运行 claude mcp list 进行确认。添加 -s user，即可让它在所有项目中使用，而不仅限于当前项目。

Claude Desktop

将服务添加到 Claude Desktop 的配置文件中。在 macOS 上，文件路径为：

~/Library/Application Support/Claude/claude_desktop_config.json

（在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json。）

最简单的打开方式是 Settings → Developer → Edit Config。在文件现有内容旁添加 mcpServers 键——不要再粘贴第二个顶层 { ... } 对象，否则文件会变成无效 JSON：

{
  "mcpServers": {
    "icloud": {
      "command": "icloud-mcp",
      "env": {
        "ICLOUD_USERNAME": "[email protected]",
        "ICLOUD_KEYRING_SERVICE": "icloud-mcp"
      }
    }
  }
}

如果文件中已包含其他键，请将 mcpServers 合并为同级键（记得在键之间添加逗号）：

{
  "someExistingSetting": "...",
  "mcpServers": { "icloud": { "...": "..." } }
}

然后完全退出 Claude Desktop（按 ⌘Q，而不只是关闭窗口），再重新打开。服务会显示为本地 MCP 服务，其工具也会变为可用。

注意：

• 首次调用时会提示访问 Keychain。 macOS 会询问是否允许 icloud-mcp 读取钥匙串项目；点击 Always Allow 可避免重复提示。
• Claude Desktop 可能会在保存自身偏好设置时重写此文件，并删除它不识别的手动添加键。如果你更改其他设置后服务消失，只需重新添加 mcpServers 块。

工具和资源

工具（由模型调用）：

工具	描述
list_mail	列出文件夹（默认为 INBOX）中的邮件，按时间从新到旧排列，可选 since_date
search_mail	对收件箱（或指定文件夹）进行全文搜索
list_folders	列出可用的 IMAP 邮箱文件夹名称
get_message	根据 UID 获取一封邮件，包含完整正文
list_events	指定日期范围内的日历事件
search_events	在指定日期范围内查找标题包含指定文本的事件
list_calendars	所有日历的名称
list_contacts	列出通讯录联系人（姓名、电子邮件、电话、组织）
search_contacts	根据姓名、组织和电子邮件中的文本查找联系人
send_mail ⚠️	发送纯文本电子邮件
reply_mail ⚠️	根据 UID 回复邮件（引用原邮件；reply_all 为可选项）
forward_mail ⚠️	根据 UID 将邮件转发给新收件人
create_event ⚠️	创建日历事件
update_event ⚠️	根据 UID 编辑事件（仅修改传入的字段）
delete_event ⚠️	根据 UID 删除事件
create_contact ⚠️	创建新联系人
update_contact ⚠️	根据 UID 编辑联系人（合并到现有 vCard 中）
delete_contact ⚠️	根据 UID 删除联系人

⚠️ 写入工具需要设置 ICLOUD_ENABLE_WRITES=1，且每项操作都需确认——参见 写入操作（选择启用）。

资源（被动上下文）：

URI	描述
icloud://mail/inbox/recent	收件箱中最新的邮件
icloud://calendar/today	今天和明天的日历事件

行为说明

• 标头为空或缺失： Subject 标头缺失或存在但为空的邮件会显示为 (no subject)；From 为空或缺失时会显示为 (unknown)。（有些邮件的主题行为空，而不是完全没有主题行——两种情况都会统一处理。）
• 摘要片段优先使用 text/plain 部分；对于仅包含 HTML 的邮件，会移除标签（丢弃 <style>/<script>/<head> 中的内容），以便仍能获得 易读的预览。
• 正文中重复封装的标头： 某些发件人（例如 USPS Informed Delivery）会在解码后的正文开头嵌入 多余的 MIME 标头块。系统会移除开头的 Content-*/MIME-Version 标头块，避免这些标头泄漏到摘要片段或正文中。
• since_date 精确到日期，并根据 IMAP 服务的时区进行计算 （iCloud 使用 UTC），因此在你当地时间中，设为今天的 since_date 可能会包含昨天深夜的邮件。

开发

.venv/bin/pytest            # run the fixture-based test suite (no live account)
.venv/bin/mcp dev -m icloud_mcp.server   # interactive MCP Inspector

安全说明

• 应用专用密码仅存储在操作系统密钥环中 — 绝不会存入 .env， 也绝不会提交到代码库。
• 只读访问（邮件、日历、联系人）无法修改任何内容；IMAP 会话以只读模式打开。
• 默认关闭写入功能。启用该功能需要设置 ICLOUD_ENABLE_WRITES=1，并且每次操作都需进行交互式确认；邮件通过与读取路径隔离的独立 SMTP 连接发送。
• 可随时从 appleid.apple.com 撤销应用专用密码，且不会影响你的 Apple ID。

许可证

MIT — 请参阅 LICENSE。

---

本项目与 Apple Inc. 无关联，也未获其认可或赞助。iCloud 是 Apple Inc. 的商标。