iCloud MCP

Cloudflare Workers에서 호스팅되는 MCP 서버로, AI 어시스턴트에게 iCloud Mail, Calendar, Contacts에 대한 네이티브 도구 액세스를 제공합니다 — IMAP, CalDAV, CardDAV를 통해 — 자격 증명이 서버를 떠나지 않으면서요.

무엇인가

iCloud MCP는 세 가지 Apple 프로토콜을 구사하고 이를 MCP 클라이언트(예: Claude)에 도구 집합으로 노출하는 단일 Cloudflare Worker입니다. 어시스턴트는 실제 iCloud 계정을 대상으로 메일을 읽고 검색하고, Drafts 폴더에 답장 초안을 작성하고, 캘린더 이벤트를 읽고 관리하고, 빈 시간을 찾고, 연락처를 조회할 수 있습니다.

한 사람이 하나의 Apple ID를 대상으로 구축되었지만, 이 계정에 개인적인 것은 아무것도 없습니다. 계정별 값은 모두 사용자가 제공하는 구성에 들어 있습니다. 배포를 참조하세요.

어시스턴트가 할 수 있는 일

• 메일 읽기 — 전송은 하지 않습니다. 메시지와 첨부 파일( PDF에서 추출한 텍스트 포함)을 나열, 검색, 읽기합니다.

• 메일 초안 작성 — iCloud Drafts 폴더에 새 메시지와 스레드 답장을 작성하고, 첨부 파일을 단계적으로 준비합니다. 전송할 수 없습니다. 사람이 모든 초안을 검토하고 직접 전송합니다. 이것은 제한이 아니라 안전 경계입니다. 보안을 참조하세요.

• 캘린더 관리 — 이벤트를 나열, 검색, 읽기, 생성, 업데이트, 삭제합니다. 파괴적이거나 누군가에게 알림을 보내는 모든 변경은 먼저 미리 보기되고 명시적 확인 단계 후에만 적용됩니다.

• 빈 시간 찾기 — 주어진 기간 동안 모든 캘린더에서 빈 시간을 찾습니다.

• 연락처 조회 — 이름 또는 이메일로 연락처를 찾습니다.

의도적으로 하지 않는 일

• 메일 전송. SMTP는 절대 사용하지 않습니다. 초안 작성 및 검토 단계는 프롬프트 주입된 이메일 콘텐츠가 사용자 이름으로 나가는 것을 막는 최후의 안전장치입니다.

• 자체적으로 작동. cron 작업, 백그라운드 감시자, 요약이 없습니다.

• 콘텐츠 캐싱. iCloud가 기록 시스템입니다. 검색 메타데이터(계정을 보유한 서버)만 24시간 동안 캐시됩니다.

• 다중 사용자 또는 다른 iCloud 서비스(Reminders, Notes, Photos) 지원.

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-ignored입니다. 추적되는 템플릿은 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-ignored된 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-ignored이며 pre-commit 훅에서 거부됩니다. 로컬 실행은 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 코드는 Node 목이 아닌 현실적인 Workers 제약 조건에서 테스트됩니다. 약 2,400개의 테스트, 실제 계정 불필요.

안전 강제

다섯 가지 안전 규칙이 scripts/forbidden-tokens.mjs에 의해 기계적으로 강제되며, 테스트 스위트와 pre-commit 훅 모두에서 실행됩니다:

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.의 상표입니다.