iCloud MCP

Un servidor MCP, alojado en Cloudflare Workers, que brinda a un asistente de IA acceso nativo por herramientas a iCloud Mail, Calendar y Contacts — a través de IMAP, CalDAV y CardDAV — sin que tus credenciales salgan jamás del servidor.

Qué es

iCloud MCP es un único Cloudflare Worker que habla tres protocolos de Apple y los expone a un cliente MCP (como Claude) como un conjunto de herramientas. El asistente puede leer y buscar tu correo, redactar respuestas en tu carpeta de Borradores, leer y gestionar eventos de calendario, encontrar tiempo libre y consultar contactos — todo contra tu cuenta real de iCloud.

Fue construido para una persona contra un solo Apple ID, pero nada de ello es personal de esa cuenta: cada valor específico de la cuenta vive en la configuración que tú proporcionas. Consulta Despliegue.

Qué puede hacer el asistente

• Leer correo que no envía — listar, buscar y leer mensajes y adjuntos (incluido texto extraído de PDFs).

• Redactar correo en tu carpeta de Borradores de iCloud — mensajes nuevos y respuestas en hilo, con adjuntos preparados. No puede enviar. Un humano revisa cada borrador y lo envía manualmente. Esto es un límite de seguridad, no una limitación. Consulta Seguridad.

• Gestionar el calendario — listar, buscar, leer, crear, actualizar y eliminar eventos. Cada cambio que sea destructivo o notifique a alguien se previsualiza primero y solo se aplica tras un paso explícito de confirmación.

• Encontrar tiempo libre en todos tus calendarios para una duración determinada.

• Buscar contactos por nombre o correo electrónico.

Qué deliberadamente no hace

• Enviar correo. Sin SMTP, nunca. El paso de redactar y revisar es la salvaguarda contra que contenido de correo inyectado por prompt salga bajo tu nombre.

• Actuar por su cuenta. Sin cron jobs, sin vigilantes en segundo plano, sin resúmenes.

• Almacenar en caché tu contenido. iCloud es el sistema de registro; solo se almacenan en caché metadatos de descubrimiento (qué servidor aloja tu cuenta), durante 24 horas.

• Soportar múltiples usuarios u otros servicios de iCloud (Recordatorios, Notas, Fotos).

Related MCP server: Apple MCP

Cómo funciona

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

• El endpoint está protegido por OAuth. Una solicitud no autenticada nunca llega a una herramienta.

• IMAP se ejecuta sobre la API de sockets TCP nativa de Workers con TLS implícito en el puerto 993 — sin puente, sin proxy. Se abre una conexión, se usa y se cierra dentro de una sola solicitud.

• CalDAV/CardDAV usan tsdav; las ubicaciones resueltas del servidor se almacenan en caché en KV.

• Tus credenciales de Apple viven solo en Cloudflare Secrets. Nunca se registran, nunca se devuelven en una respuesta y nunca se colocan en un mensaje de error.

Para el diseño completo — flujo de solicitudes, internals de transporte, la aplicación de seguridad y el mapa de módulos — consulta ARCHITECTURE.md.

Herramientas

23 herramientas en cinco grupos. Cada descripción de herramienta lleva un aviso de contenido no confiable; los títulos de eventos, cuerpos de mensajes y campos de contacto se tratan como datos, nunca como instrucciones.

Diagnóstico

Correo

Calendario

Contactos

Los parámetros de entrada completos de cada herramienta están en las propias descripciones de las herramientas y en ARCHITECTURE.md.

Requisitos

Despliegue

Cada valor específico de la cuenta va en wrangler.jsonc, que está en git-ignore. La plantilla rastreada es wrangler.jsonc.example. npm install copia la plantilla en su lugar en la primera ejecución.

1. Clonar e instalar

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

2. Crear los bindings de almacenamiento

Cada comando imprime un id. Pégalo en la entrada correspondiente en 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

Añade una regla de ciclo de vida al bucket para que las subidas preparadas caduquen después de un día (panel de Cloudflare → R2 → tu bucket → Configuración → Reglas de ciclo de vida de objetos: prefijo staging/, eliminar después de 1 día). Esto es obligatorio — el token de preparación caduca a las 24 h y los bytes no deben sobrevivirle por mucho.

3. Rellenar wrangler.jsonc

Edita estos valores en tu wrangler.jsonc (en git-ignore):

• routes[0].pattern → tu dominio personalizado (p. ej. icloud-mcp.your-domain.example)

• vars.R2_ACCOUNT_ID → tu id de cuenta de Cloudflare

• kv_namespaces[].id → los tres ids del paso 2

El nombre de host se incorpora automáticamente en la compilación desde routes[0].pattern; nunca lo editas en el código.

4. Establecer los secretos

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

Consulta .dev.vars.example para saber qué es cada secreto.

5. Desplegar y verificar

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

Conectar un cliente MCP

El endpoint MCP es https://your-domain.example/mcp. Usa OAuth 2.1 con Registro Dinámico de Clientes.

1. Añade la URL del conector (https://your-domain.example/mcp) en tu cliente MCP.

2. El cliente te envía a la página /authorize.

3. Introduce tu AUTH_SECRET y aprueba.

La lista de permitidos de origen de redirección es https://claude.ai más loopback. Para autorizar un cliente en un origen diferente, añádelo en src/auth/login-handler.ts.

Desarrollo local

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

.dev.vars está en git-ignore y es rechazado por el hook de pre-commit. Las ejecuciones locales usan el KV/R2 local de Miniflare — no se toca almacenamiento real de Cloudflare.

No apuntes pruebas ni ningún paso automatizado a tu Apple ID real. El conjunto de pruebas usa credenciales falsas a propósito (D-09).

Pruebas

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

Las pruebas se ejecutan dentro del runtime real de workerd mediante @cloudflare/vitest-pool-workers, por lo que el código de sockets y DAV se ejercita contra restricciones realistas de Workers, no un mock de Node. ~2,400 pruebas, sin cuenta real requerida.

Aplicación de seguridad

Cinco reglas de seguridad se aplican mecánicamente mediante scripts/forbidden-tokens.mjs, que se ejecuta tanto desde el conjunto de pruebas como desde un hook de pre-commit:

1. Sin rutas de transporte TLS oportunista (solo TLS implícito en 993).

2. Sin envío de correo — sin SMTP, una ruta de escritura de borradores, aplicada como recuento.

3. Solo un módulo puede abrir un socket TCP.

4. Ninguna credencial llega jamás a un registro o a un error (no hay registro en src/).

5. Leer correo nunca lo marca como leído (buzones abiertos en solo lectura, búsquedas con peek).

Cambiar cualquiera de estas es un cambio en el límite de seguridad del proyecto. Las reglas, sus razones y cómo se aplican están documentadas en ARCHITECTURE.md → Modelo de seguridad.

Estructura del proyecto

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

Pila tecnológica

Cloudflare Workers · TypeScript · MCP SDK v2 (@modelcontextprotocol/server) · agents (createMcpHandler) · @cloudflare/workers-oauth-provider · tsdav (CalDAV/CardDAV) · ical.js (iCalendar y vCard) · postal-mime (MIME) · unpdf (texto PDF) · aws4fetch (presign R2) · zod (esquemas).

Contribuciones

Las incidencias y las solicitudes de extracción son bienvenidas. Antes de cambiar cualquier cosa en src/, lee ARCHITECTURE.md — especialmente el Modelo de seguridad, que el escáner aplica en cada commit. Para informar de un problema de seguridad, consulta SECURITY.md.

Licencia

MIT © 2026 Russell Moore.

Este proyecto no está afiliado ni respaldado por Apple Inc. "iCloud" y "Apple" son marcas comerciales de Apple Inc.