iCloud MCP

Ein MCP-Server, gehostet auf Cloudflare Workers, der einem KI-Assistenten nativen Tool-Zugriff auf iCloud Mail, Kalender und Kontakte bietet – über IMAP, CalDAV und CardDAV – ohne dass Ihre Anmeldedaten jemals den Server verlassen.

Was es ist

iCloud MCP ist ein einzelner Cloudflare Worker, der drei Apple-Protokolle spricht und sie einem MCP-Client (wie Claude) als eine Reihe von Tools zur Verfügung stellt. Der Assistent kann Ihre E-Mails lesen und durchsuchen, Entwürfe in Ihren Entwürfe-Ordner schreiben, Kalenderereignisse lesen und verwalten, freie Zeiten finden und Kontakte nachschlagen – alles gegen Ihr echtes iCloud-Konto.

Es wurde für eine Person mit einer Apple-ID gebaut, aber nichts daran ist persönlich auf dieses Konto zugeschnitten: Jeder kontospezifische Wert befindet sich in der Konfiguration, die Sie bereitstellen. Siehe Bereitstellung.

Was der Assistent kann

• E-Mails lesen – es sendet keine: Listen, durchsuchen und lesen Sie Nachrichten und Anhänge (einschließlich aus PDFs extrahiertem Text).

• E-Mails entwerfen in Ihren iCloud-Entwürfe-Ordner – neue Nachrichten und Thread-Antworten mit gestaffelten Anhängen. Es kann nicht senden. Ein Mensch überprüft jeden Entwurf und sendet ihn von Hand. Dies ist eine Sicherheitsgrenze, keine Einschränkung. Siehe Sicherheit.

• Kalender verwalten – Ereignisse auflisten, suchen, lesen, erstellen, aktualisieren und löschen. Jede Änderung, die destruktiv ist oder jemanden benachrichtigt, wird zuerst in der Vorschau angezeigt und erst nach einem expliziten Bestätigungsschritt angewendet.

• Freie Zeiten finden über alle Ihre Kalender für eine bestimmte Dauer.

• Kontakte nachschlagen nach Name oder E-Mail.

Was es bewusst nicht tut

• E-Mails senden. Kein SMTP, niemals. Der Entwurfs- und Überprüfungsschritt ist die Absicherung gegen prompt-injizierte E-Mail-Inhalte, die unter Ihrem Namen ausgehen.

• Eigenständig handeln. Keine Cron-Jobs, keine Hintergrund-Überwacher, keine Zusammenfassungen.

• Ihre Inhalte zwischenspeichern. iCloud ist die Quelle der Wahrheit; nur Erkennungsmetadaten (welcher Server Ihr Konto enthält) werden für 24 Stunden zwischengespeichert.

• Mehrere Benutzer oder andere iCloud-Dienste (Erinnerungen, Notizen, Fotos) unterstützen.

Related MCP server: icloud-mcp

So funktioniert es

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

• Der Endpunkt ist OAuth-geschützt. Eine nicht authentifizierte Anfrage erreicht niemals ein Tool.

• IMAP läuft über die Workers-native TCP-Socket-API mit implizitem TLS auf Port 993 – keine Brücke, kein Proxy. Eine Verbindung wird innerhalb einer einzelnen Anfrage geöffnet, verwendet und geschlossen.

• CalDAV/CardDAV verwenden tsdav; aufgelöste Serverstandorte werden in KV zwischengespeichert.

• Ihre Apple-Anmeldedaten liegen nur in Cloudflare Secrets. Sie werden niemals protokolliert, niemals in einer Antwort zurückgegeben und niemals in eine Fehlermeldung eingefügt.

Für das vollständige Design – Anfragefluss, Transport-Interna, die Sicherheitsdurchsetzung und die Modulkarte – siehe ARCHITECTURE.md.

Tools

23 Tools in fünf Gruppen. Jede Tool-Beschreibung trägt einen Hinweis auf nicht vertrauenswürdige Inhalte; Ereignistitel, Nachrichtentexte und Kontaktfelder werden als Daten behandelt, niemals als Anweisungen.

Diagnose

E-Mail

Kalender

Kontakte

Vollständige Eingabeparameter für jedes Tool finden Sie in den Tool-Beschreibungen selbst und in ARCHITECTURE.md.

Anforderungen

Bereitstellung

Jeder kontospezifische Wert wird in wrangler.jsonc eingetragen, das git-ignoriert ist. Die nachverfolgte Vorlage ist wrangler.jsonc.example. npm install kopiert die Vorlage beim ersten Lauf an ihren Platz.

1. Klonen und installieren

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

2. Speicherbindungen erstellen

Jeder Befehl gibt eine ID aus. Fügen Sie sie in den entsprechenden Eintrag in wrangler.jsonc ein.

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

Fügen Sie dem Bucket eine Lebenszyklusregel hinzu, damit gestaffelte Uploads nach einem Tag ablaufen (Cloudflare-Dashboard → R2 → Ihr Bucket → Einstellungen → Objekt-Lebenszyklusregeln: Präfix staging/, nach 1 Tag löschen). Dies ist erforderlich – das Staging-Token läuft nach 24 Stunden ab und die Bytes dürfen nicht viel länger überleben.

3. wrangler.jsonc ausfüllen

• routes[0].pattern → Ihre benutzerdefinierte Domain (z. B. icloud-mcp.your-domain.example)

• vars.R2_ACCOUNT_ID → Ihre Cloudflare-Konto-ID

• kv_namespaces[].id → die drei IDs aus Schritt 2

Der Hostname wird automatisch aus routes[0].pattern in den Build eingebacken; Sie bearbeiten ihn nie im Code.

4. Die Secrets festlegen

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

Siehe .dev.vars.example für die Bedeutung jedes Secrets.

5. Bereitstellen und verifizieren

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

Einen MCP-Client verbinden

Der MCP-Endpunkt ist https://your-domain.example/mcp. Er verwendet OAuth 2.1 mit dynamischer Client-Registrierung.

1. Fügen Sie die Connector-URL (https://your-domain.example/mcp) in Ihrem MCP-Client hinzu.

2. Der Client sendet Sie zur /authorize-Seite.

3. Geben Sie Ihr AUTH_SECRET ein und genehmigen Sie.

Die Redirect-Origin-Allowlist ist https://claude.ai plus Loopback. Um einen Client auf einer anderen Origin zu autorisieren, fügen Sie ihn in src/auth/login-handler.ts hinzu.

Lokale Entwicklung

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

.dev.vars ist git-ignoriert und wird vom Pre-Commit-Hook abgelehnt. Lokale Läufe verwenden Miniflare's lokales KV/R2 – kein Live-Cloudflare-Speicher wird berührt.

Richten Sie keine Tests oder automatisierten Schritte auf Ihre echte Apple-ID. Die Suite verwendet absichtlich gefälschte Anmeldedaten (D-09).

Testen

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

Tests laufen innerhalb der echten workerd-Laufzeit über @cloudflare/vitest-pool-workers, sodass Socket- und DAV-Code gegen realistische Workers-Einschränkungen getestet wird, nicht gegen einen Node-Mock. ~2.400 Tests, kein Live-Konto erforderlich.

Sicherheitsdurchsetzung

Fünf Sicherheitsregeln werden mechanisch von scripts/forbidden-tokens.mjs durchgesetzt, das sowohl aus der Testsuite als auch aus einem Pre-Commit-Hook läuft:

1. Keine opportunistischen TLS-Transportpfade (nur implizites TLS auf 993).

2. Kein E-Mail-Versand – kein SMTP, ein Entwurfs-Schreibpfad, als Anzahl durchgesetzt.

3. Nur ein einziges Modul darf einen TCP-Socket öffnen.

4. Keine Anmeldedaten dürfen jemals in ein Log oder einen Fehler gelangen (es gibt kein Logging in src/).

5. Das Lesen von E-Mails markiert sie nie als gelesen (Mailboxen werden schreibgeschützt geöffnet, Peeking-Fetches).

Das Ändern einer dieser Regeln ist eine Änderung der Sicherheitsgrenze des Projekts. Die Regeln, ihre Gründe und wie sie durchgesetzt werden, sind in ARCHITECTURE.md → Sicherheitsmodell dokumentiert.

Projektstruktur

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

Technologie-Stack

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

Mitwirken

Issues und Pull-Requests sind willkommen. Bevor Sie etwas unter src/ ändern, lesen Sie ARCHITECTURE.md – insbesondere das Sicherheitsmodell, das der Scanner bei jedem Commit durchsetzt. Um ein Sicherheitsproblem zu melden, siehe SECURITY.md.

Lizenz

MIT © 2026 Russell Moore.

Dieses Projekt ist nicht mit Apple Inc. verbunden oder von ihr unterstützt. „iCloud“ und „Apple“ sind Marken von Apple Inc.