iCloud MCP

一个 MCP 服务器，托管在 Cloudflare Workers 上，为 AI 助手提供对 iCloud 邮件、日历和通讯录 的原生工具访问——通过 IMAP、CalDAV 和 CardDAV——而您的凭据永远不会离开服务器。

它是什么

iCloud MCP 是一个单一的 Cloudflare Worker，它支持三种 Apple 协议，并将它们作为一组工具暴露给 MCP 客户端（如 Claude）。助手可以阅读和搜索您的邮件，将回复草稿写入您的草稿文件夹，阅读和管理日历事件，查找空闲时间，以及查找联系人——所有这些都针对您的真实 iCloud 账户。

它是为一个人针对一个 Apple ID 构建的，但其中没有任何内容与该账户个人相关：每个特定于账户的值都存在于您提供的配置中。请参阅 部署。

助手可以做什么

• 阅读邮件（它不会发送）——列出、搜索和阅读消息和附件（包括从 PDF 中提取的文本）。

• 起草邮件到您的 iCloud 草稿文件夹——新消息和线程回复，带有暂存附件。它不能发送。 人类会审查每份草稿并手动发送。这是一个安全边界，而不是限制。请参阅 安全。

• 管理日历——列出、搜索、阅读、创建、更新和删除事件。每个具有破坏性或通知他人的更改都会先预览，并且仅在明确的确认步骤后应用。

• 查找空闲时间——在您的所有日历中查找给定时长的空闲时段。

• 按姓名或电子邮件查找联系人。

它刻意不做什么

• 发送邮件。 绝不使用 SMTP。草稿和审查步骤是防止提示注入的电子邮件内容以您的名义发出的后盾。

• 自主行动。 没有 cron 作业，没有后台监视器，没有摘要。

• 缓存您的内容。 iCloud 是记录系统；只有发现元数据（哪个服务器持有您的账户）会被缓存 24 小时。

• 支持多用户或其他 iCloud 服务（提醒事项、备忘录、照片）。

Related MCP server: Apple MCP

工作原理

MCP client (Claude)
      │  HTTPS, OAuth 2.1 bearer token
      ▼
Cloudflare Worker  ──  OAuth provider gates every request
      │                (@cloudflare/workers-oauth-provider)
      ▼
MCP handler (/mcp)  ──  builds a fresh server per request
      │
      ├─ Mail tools  ──▶ IMAP over TLS (raw TCP socket) ──▶ imap.mail.me.com:993
      ├─ Cal tools   ──▶ CalDAV over HTTPS  ──▶ caldav.icloud.com
      └─ Contact tools ▶ CardDAV over HTTPS ──▶ contacts.icloud.com

• 端点受 OAuth 保护。未经身份验证的请求永远不会到达工具。

• IMAP 通过 Workers 原生 TCP 套接字 API 运行，在端口 993 上使用隐式 TLS——没有桥接，没有代理。连接在单个请求内打开、使用和关闭。

• CalDAV/CardDAV 使用 tsdav；解析的服务器位置缓存在 KV 中。

• 您的 Apple 凭据仅存在于 Cloudflare Secrets 中。它们永远不会被记录，永远不会在响应中返回，也永远不会出现在错误消息中。

有关完整设计——请求流程、传输内部机制、安全执行和模块映射——请参阅 ARCHITECTURE.md。

工具

五个组中共有 23 个工具。每个工具描述都带有不受信任内容通知；事件标题、消息正文和联系人字段被视为数据，而不是指令。

诊断

邮件

日历

通讯录

每个工具的完整输入参数在工具描述本身和 ARCHITECTURE.md 中。

要求

部署

每个特定于账户的值都放在 wrangler.jsonc 中，该文件被 git 忽略。跟踪的模板是 wrangler.jsonc.example。npm install 会在首次运行时将模板复制到位。

1. 克隆并安装

git clone https://github.com/russellkmoore/icloud-mcp.git
cd icloud-mcp
npm install          # also copies wrangler.jsonc.example -> wrangler.jsonc

2. 创建存储绑定

每个命令都会打印一个 id。将其粘贴到 wrangler.jsonc 中相应的条目中。

npx wrangler kv namespace create OAUTH_KV
npx wrangler kv namespace create DAV_CACHE
npx wrangler kv namespace create CONFIRM_KV

npx wrangler r2 bucket create icloud-mcp-attachments

向存储桶添加生命周期规则，使暂存上传在一天后过期（Cloudflare 仪表板 → R2 → 您的存储桶 → 设置 → 对象生命周期规则：前缀 staging/，1 天后删除）。这是必需的——暂存令牌在 24 小时后过期，字节不能比它存活更久。

3. 填写 wrangler.jsonc

在您被 git 忽略的 wrangler.jsonc 中编辑这些值：

• routes[0].pattern → 您的自定义域名（例如 icloud-mcp.your-domain.example）

• vars.R2_ACCOUNT_ID → 您的 Cloudflare 账户 id

• kv_namespaces[].id → 步骤 2 中的三个 id

主机名会自动从 routes[0].pattern 烘焙到构建中；您永远不需要在代码中编辑它。

4. 设置密钥

npx wrangler secret put AUTH_SECRET            # your login password for /authorize
npx wrangler secret put APPLE_ID               # the account's Apple ID (email)
npx wrangler secret put APPLE_APP_PASSWORD     # app-specific password, not the real one
npx wrangler secret put CONFIRM_SECRET         # e.g. `openssl rand -base64 32`
npx wrangler secret put R2_ACCESS_KEY_ID       # from an R2 S3 API token,
npx wrangler secret put R2_SECRET_ACCESS_KEY   #   Object Read & Write, scoped to the bucket

请参阅 .dev.vars.example 了解每个密钥是什么。

5. 部署并验证

npm test          # optional: full suite against a local workerd (no live account needed)
npm run deploy
npm run smoke     # confirms the live endpoint refuses an unauthenticated request

连接 MCP 客户端

MCP 端点是 https://your-domain.example/mcp。它使用带有动态客户端注册的 OAuth 2.1。

1. 在您的 MCP 客户端中添加连接器 URL（https://your-domain.example/mcp）。

2. 客户端将您发送到 /authorize 页面。

3. 输入您的 AUTH_SECRET 并批准。

重定向来源允许列表是 https://claude.ai 加上回环。要授权不同来源的客户端，请在 src/auth/login-handler.ts 中添加它。

本地开发

cp .dev.vars.example .dev.vars   # then fill in the values
npx wrangler dev                 # runs the Worker locally

.dev.vars 被 git 忽略，并且被预提交钩子拒绝。本地运行使用 Miniflare 的本地 KV/R2——不会触及实时的 Cloudflare 存储。

不要将测试或任何自动化步骤指向您的真实 Apple ID。测试套件故意使用假凭据（D-09）。

测试

npm test          # full suite
npm run typecheck # tsc --noEmit
npm run scan      # the safety scanner (see below)

测试通过 @cloudflare/vitest-pool-workers 在真实的 workerd 运行时中运行，因此套接字和 DAV 代码会在真实的 Workers 约束下进行测试，而不是 Node 模拟。~2,400 个测试，无需真实账户。

安全执行

五个安全规则由 scripts/forbidden-tokens.mjs 机械地强制执行，该脚本从测试套件和预提交钩子中运行：

1. 没有机会性 TLS 传输路径（仅限 993 上的隐式 TLS）。

2. 不发送邮件——没有 SMTP，只有一个草稿写入路径，以计数方式强制执行。

3. 只有一个模块可以打开 TCP 套接字。

4. 任何凭据都不会进入日志或错误（src/ 中没有日志记录）。

5. 阅读邮件永远不会将其标记为已读（邮箱以只读方式打开，使用窥视获取）。

更改其中任何一项都是对项目安全边界的更改。规则、其原因以及执行方式记录在 ARCHITECTURE.md → 安全模型 中。

项目结构

src/
  index.ts            Worker entry (the OAuth provider)
  env.ts              binding surface (KV, R2, vars, secrets)
  auth/               OAuth options + the /authorize login handler
  mcp/                MCP handler, per-request server factory, tool registrations
  mail/               IMAP: the one socket importer, session orchestrator, MIME
  dav/                CalDAV/CardDAV: transport, discovery, calendar/contacts, parsers
  staging/            R2 attachment staging + presigned uploads
  feed/               subscription-feed fetch (calendar subscriptions)
scripts/              hostname generation, the safety scanner, smoke test
test/                 ~2,400 tests, run inside workerd

技术栈

Cloudflare Workers · TypeScript · MCP SDK v2 (@modelcontextprotocol/server) · agents (createMcpHandler) · @cloudflare/workers-oauth-provider · tsdav (CalDAV/CardDAV) · ical.js (iCalendar 和 vCard) · postal-mime (MIME) · unpdf (PDF 文本) · aws4fetch (R2 预签名) · zod (模式)。

贡献

欢迎提交问题和拉取请求。在更改 src/ 下的任何内容之前，请阅读 ARCHITECTURE.md——尤其是 安全模型，扫描器会在每次提交时强制执行。要报告安全问题，请参阅 SECURITY.md。

许可证

MIT © 2026 Russell Moore.

本项目与 Apple Inc. 无关联，也未获得其认可。“iCloud”和“Apple”是 Apple Inc. 的商标。