iCloud MCP

Сервер MCP, размещённый на Cloudflare Workers, который предоставляет ИИ-ассистенту нативный доступ к инструментам iCloud Mail, Calendar и Contacts — через IMAP, CalDAV и CardDAV — без того, чтобы ваши учётные данные когда-либо покидали сервер.

Что это такое

iCloud MCP — это один Cloudflare Worker, который говорит на трёх протоколах Apple и предоставляет их MCP-клиенту (например, Claude) в виде набора инструментов. Ассистент может читать и искать вашу почту, создавать черновики ответов в папке Drafts, читать и управлять событиями календаря, находить свободное время и искать контакты — всё это против вашей реальной учётной записи iCloud.

Он был создан для одного человека с одним Apple ID, но ничто в нём не является личным для этой учётной записи: каждое значение, специфичное для аккаунта, хранится в конфигурации, которую вы предоставляете. См. Развёртывание.

Что может делать ассистент

• Читать почту — он не отправляет: список, поиск и чтение сообщений и вложений (включая текст, извлечённый из PDF).

• Создавать черновики в вашей папке iCloud Drafts — новые сообщения и ответы в ветках, с подготовленными вложениями. Он не может отправлять. Человек проверяет каждый черновик и отправляет его вручную. Это граница безопасности, а не ограничение. См. Безопасность.

• Управлять календарём — список, поиск, чтение, создание, обновление и удаление событий. Каждое изменение, которое является разрушительным или уведомляет кого-либо, сначала предпросматривается и применяется только после явного шага подтверждения.

• Находить свободное время во всех ваших календарях на заданную длительность.

• Искать контакты по имени или электронной почте.

Что он намеренно не делает

• Не отправляет почту. Никакого SMTP, никогда. Шаг черновика и проверки — это защита от отправки содержимого, внедрённого через промпт, под вашим именем.

• Не действует сам. Никаких cron-задач, фоновых наблюдателей, дайджестов.

• Не кэширует ваш контент. iCloud — это система записи; кэшируются только метаданные обнаружения (какой сервер содержит вашу учётную запись), на 24 часа.

• Не поддерживает несколько пользователей или другие сервисы iCloud (Reminders, Notes, Photos).

Related MCP server: icloud-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 работает через нативный TCP-сокет Workers с неявным TLS на порту 993 — без моста, без прокси. Соединение открывается, используется и закрывается в рамках одного запроса.

• 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. Создание привязок хранилища

Каждая команда выводит идентификатор. Вставьте его в соответствующую запись в 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 → ваша корзина → Settings → Object lifecycle rules: префикс staging/, удалять через 1 день). Это обязательно — токен подготовки истекает через 24 часа, и байты не должны переживать его намного дольше.

3. Заполните wrangler.jsonc

Отредактируйте эти значения в вашем игнорируемом git wrangler.jsonc:

• routes[0].pattern → ваш пользовательский домен (например, icloud-mcp.your-domain.example)

• vars.R2_ACCOUNT_ID → ваш идентификатор аккаунта Cloudflare

• kv_namespaces[].id → три идентификатора из шага 2

Имя хоста автоматически встраивается в сборку из 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. Добавьте URL коннектора (https://your-domain.example/mcp) в вашем MCP-клиенте.

2. Клиент перенаправит вас на страницу /authorize.

3. Введите ваш AUTH_SECRET и подтвердите.

Список разрешённых источников перенаправления — https://claude.ai плюс loopback. Чтобы авторизовать клиента на другом источнике, добавьте его в 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 и отклоняется pre-commit хуком. Локальные запуски используют локальные KV/R2 Miniflare — никакое живое хранилище Cloudflare не затрагивается.

Не направляйте тесты или любые автоматизированные шаги на ваш реальный Apple ID. Набор использует фиктивные учётные данные намеренно (D-09).

Тестирование

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

Тесты запускаются внутри реального рантайма workerd через @cloudflare/vitest-pool-workers, поэтому код сокетов и DAV проверяется в реалистичных ограничениях Workers, а не в Node-моке. ~2400 тестов, без необходимости в живой учётной записи.

Обеспечение безопасности

Пять правил безопасности механически обеспечиваются scripts/forbidden-tokens.mjs, который запускается как из набора тестов, так и из pre-commit хука:

1. Нет путей транспорта с оппортунистическим TLS (только неявный TLS на 993).

2. Нет отправки почты — нет SMTP, один путь записи черновиков, обеспечивается как счётчик.

3. Только один модуль может открывать TCP-сокет.

4. Никакие учётные данные никогда не попадают в лог или ошибку (в src/ нет логирования).

5. Чтение почты никогда не помечает её как прочитанную (почтовые ящики открываются только для чтения, выборки с peek).

Изменение любого из этих правил — это изменение границы безопасности проекта. Правила, их причины и способы обеспечения описаны в 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 (схемы).

Вклад

Приветствуются issues и pull request'ы. Прежде чем менять что-либо в src/, прочитайте ARCHITECTURE.md — особенно Модель безопасности, которую сканер проверяет при каждом коммите. Чтобы сообщить о проблеме безопасности, см. SECURITY.md.

Лицензия

MIT © 2026 Russell Moore.

Этот проект не связан с Apple Inc. и не одобрен ею. "iCloud" и "Apple" являются товарными знаками Apple Inc.