iCloud Mail

iCloud Mail MCP

一个用于 iCloud Mail 的模型上下文协议（MCP）服务。让大模型通过 IMAP 和 SMTP 读取、搜索、归档和发送你的 Apple 邮件。

所有操作都在你的设备上运行：你的凭据和邮件绝不会传给第三方。网络通信和 MIME 解析仅使用 Python 标准库。

主要功能

• 默认只读。 搜索和读取工具使用 SELECT ... readonly 和 BODY.PEEK——不会在你不知情的情况下将邮件标记为已读、移动或删除。
• 搜索所有文件夹，而不只是收件箱。 回复会根据邮件规则归档；search_all_folders 可以在收件箱搜索无法找到的地方找到它们。
• 发送前先保存草稿。 save_draft 会将邮件保存到“草稿”文件夹，供你审核。send_email 也可用，但与之分离，需要明确调用。
• 不会销毁邮件。 没有删除邮件的工具，而且 delete_mailbox 会拒绝删除仍包含邮件的文件夹。
• 支持真实的 iCloud MIME 格式。 包括 Modified UTF-7 文件夹名称、quoted-printable、错误的字符集声明、纯 HTML 邮件以及服务器端的重音字符搜索。

要求

• Python 3.11 或更高版本，以及 uv
• 已启用双重认证的 iCloud 账户
• App 专用密码——iCloud 不允许通过 IMAP 使用你的主密码

开始使用

发布到 PyPI 后，无需克隆：

uvx --from icloud-mail-mcp icloud-mcp-setup     # interactive configuration
uvx --from icloud-mail-mcp icloud-mcp           # run the server

从源代码安装：

git clone https://github.com/JulienRabault/icloud-mcp.git
cd icloud-mcp
uv sync
uv run python -m icloud_mcp.setup

设置命令会要求你提供邮箱地址和 App 专用密码，测试连接，写入 .env，然后打印客户端所需的准确配置块。

在 account.apple.com →“登录与安全”→“App 专用密码”中生成 App 专用密码。

标准配置适用于大多数客户端：

{
  "mcpServers": {
    "icloud-mail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]
    }
  }
}

claude mcp add icloud-mail --scope user -- uv run --directory /path/to/icloud-mcp python -m icloud_mcp

[mcp_servers.icloud-mail]
command = "uv"
args = ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]

MCP 服务会在客户端启动时加载——编辑配置后，请重启客户端。

工具

读取——以下工具均不会修改邮箱：

写入——操作均需明确指定：

没有任何工具会销毁邮件。delete_mailbox 会拒绝删除仍有邮件的文件夹——请先将邮件移出，这样决定权就在你手中。

附件数据不会经过模型：save_attachments 会写入文件并返回路径。对来自邮件的文件名会进行净化处理——这些名称是不可信的输入，而不是可信路径。

资源

提示词

不使用 MCP 客户端进行自动化

examples/ 中包含使用相同模块的独立脚本——将它们配置到 cron 或 Task Scheduler 中：

uv run python examples/daily_digest.py           # what arrived today
uv run python examples/watch_sender.py acme.com  # exit 1 if nothing new
uv run python examples/waiting_on_reply.py       # threads nobody answered
uv run python examples/auto_file.py --apply      # file mail by rules

所有脚本都支持 --json，便于通过管道传递。请参阅 examples/README.md。

随附技能

skills/mailbox-search/ 是一项 Claude Code 技能，会强制搜索所有文件夹，然后才能断定某封邮件不存在：

cp -r skills/mailbox-search ~/.claude/skills/

此处处理的 iCloud 特性

如果你要编写自己的 IMAP 客户端来连接 iCloud，以下内容值得了解：

• SEARCH 返回的 UID 顺序不固定。 RFC 3501 未保证排序，而 iCloud 实际上确实会返回未排序的列表。直接取响应末尾的条目会得到错误的邮件——应先按数字排序。
• 没有 MOVE，也没有 UIDPLUS。 移动邮件需要执行 COPY + \Deleted + EXPUNGE，而 EXPUNGE 会清除文件夹中所有 \Deleted 邮件。若文件夹中存在不在请求批次内的已删除邮件，move_emails 会拒绝运行，否则这些邮件会被一并销毁。
• SEARCH CHARSET UTF-8 可用。 含重音符号的查询会在服务器端对整个邮箱进行搜索。对于拒绝此操作的服务器，客户端会采用备用方案，并通过响应中的 filtered_client_side 标记。
• 文件夹名称使用改良版 UTF-7（RFC 3501），由 utf7.py 实现。
• 字符集声明可能不可靠。 声明的字符集无法使用时，正文会回退到 latin-1；没有 text/plain 部分时，则会回退到去除标签后的 HTML。

安全说明

• 凭据保存在 .env（已加入 gitignore）或环境变量中，绝不会写入代码。Settings.__repr__ 会省略密码。
• 邮件内容是数据，不是指令。服务器会告知客户端，绝不可执行收到的邮件中包含的指令。
• 只有在对话中用户批准确切内容或确切邮件列表后，才应运行 send_email 和 move_emails。

开发

uv run pytest -q

49 项离线测试——无需网络，也无需凭据。CI 会在 Linux、macOS 和 Windows 上使用 Python 3.11 至 3.13 运行这些测试。

src/icloud_mcp/
  config.py        env / .env loading
  utf7.py          modified UTF-7 for folder names
  models.py        frozen Pydantic models
  mime.py          header, body and attachment decoding
  imap_client.py   connection, LIST, STATUS, SELECT, FETCH
  search.py        SEARCH criteria, threading, multi-folder search
  smtp_client.py   MIME building, SMTP send, copy to Sent
  attachments.py   attachment extraction, filename sanitising
  drafts.py        APPEND to Drafts
  flags.py         \Seen, \Flagged, \Answered
  move.py          COPY + EXPUNGE with the anti-purge guard
  mailboxes.py     create, rename, delete (empty only)
  organize.py      rule-based filing
  server.py        tools, resources, prompts
  setup_wizard.py  interactive configuration
  cli.py           terminal checks

贡献

欢迎提交问题和拉取请求。测试必须可离线通过——不得有任何测试需要真实邮箱。

许可证

MIT