Skip to main content
Glama
iCloud MCP

iCloud MCP

iCloud MCP

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

License: MIT Platform: Cloudflare Workers Protocol: MCP


무엇인가

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: 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은 Workers 네이티브 TCP 소켓 API를 통해 포트 993에서 암시적 TLS로 실행됩니다 — 브리지도 프록시도 없습니다. 연결은 단일 요청 내에서 열리고, 사용되고, 닫힙니다.

  • CalDAV/CardDAV는 tsdav를 사용합니다. 확인된 서버 위치는 KV에 캐시됩니다.

  • Apple 자격 증명은 Cloudflare Secrets에만 존재합니다. 로그에 기록되지 않고, 응답에 반환되지 않으며, 오류 메시지에 포함되지 않습니다.

전체 설계 — 요청 흐름, 전송 내부 구조, 안전 강제, 모듈 맵 — 은 ARCHITECTURE.md 를 참조하세요.


도구

다섯 그룹의 23개 도구. 모든 도구 설명에는 신뢰할 수 없는 콘텐츠 주의 문구가 포함됩니다. 이벤트 제목, 메시지 본문, 연락처 필드는 데이터로 취급되며 지시사항으로 취급되지 않습니다.

진단

도구

기능

mail_imap_diagnose

iCloud IMAP 연결, 인증, 기능을 확인합니다.

dav_diagnose

CalDAV/CardDAV 검색을 확인합니다: 확인된 URL, 샤드 호스트, 캐시 적중, 타이밍.

메일

도구

기능

mail_list_folders

역할과 개수가 포함된 메일 폴더를 나열합니다.

mail_list_messages

폴더의 메시지를 최신순으로 나열합니다(메타데이터 + 제한된 스니펫, 본문은 제외).

mail_list_unread

폴더의 읽지 않은 메일을 나열합니다.

mail_search

키워드, 발신자, 날짜 범위로 한 폴더를 검색합니다.

mail_get_message

불투명 ID로 메시지 하나를 전체 읽기합니다.

mail_get_attachment

첨부 파일 하나를 텍스트로 읽습니다(PDF 텍스트는 추출됨).

mail_compose_new

새 메시지를 Drafts에 작성합니다(전송되지 않음).

mail_compose_reply

메시지에 Drafts에서 스레드로 답장을 작성합니다(전송되지 않음).

mail_stage_attachment

초안에 첨부할 파일을 준비합니다(메시지, 원시 바이트 또는 업로드 URL에서).

mail_confirm_upload

사전 서명된 첨부 파일 업로드를 완료합니다.

캘린더

도구

기능

calendar_list_calendars

캘린더를 나열합니다: id, 이름, 색상, 구독 플래그.

calendar_list_events

날짜 범위의 이벤트를 나열합니다(반복 이벤트는 발생 항목으로 확장됨).

calendar_get_event

불투명 ID로 이벤트 하나를 전체 읽기합니다.

calendar_search

범위 내에서 키워드 또는 참석자로 이벤트를 찾습니다.

calendar_find_free_slots

기간과 범위에 대해 모든 캘린더에서 빈 슬롯을 찾습니다.

calendar_create_event

이벤트를 생성합니다. 참석자가 있으면 먼저 미리 보고 확인을 반환합니다.

calendar_update_event

변경 사항을 미리 봅니다; calendar_commit 전에는 아무것도 쓰지 않습니다.

calendar_delete_event

이벤트 하나 삭제를 미리 봅니다; calendar_commit 전에는 아무것도 쓰지 않습니다.

calendar_commit

확인 토큰을 사용하여 미리 본 생성/업데이트/삭제를 적용합니다.

연락처

도구

기능

contacts_search

이름 또는 이메일로 연락처를 찾습니다(행에 주소 포함).

contacts_get

불투명 ID로 연락처 하나를 전체 읽기합니다.

각 도구의 전체 입력 매개변수는 도구 설명 자체와 ARCHITECTURE.md에 있습니다.


요구 사항

요구 사항

이유

Cloudflare 계정, Workers 유료 플랜

무료 티어의 10ms CPU 예산으로는 MIME 본문과 PDF 첨부 파일을 파싱할 수 없습니다.

Cloudflare의 도메인

workers.dev 및 미리 보기 URL은 설계상 비활성화되어 있으므로 사용자 지정 도메인 경로가 필요합니다.

앱별 암호가 있는 Apple ID

iCloud는 2단계 인증이 활성화된 계정(그럴 수밖에 없음)에 IMAP/DAV용 앱별 암호를 요구합니다.

Node.js 20+ 및 npm

Wrangler 및 Vitest 도구 체인용입니다.


배포

계정별 값은 모두 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.의 상표입니다.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with read-only access to iCloud mail and calendar via IMAP and CalDAV, with opt-in write support for sending mail, managing events, and contacts.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables local AI agents to search and read iCloud Mail, draft and send reviewed replies, and manage calendar events via a local MCP connection.
      19
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to read iCloud Mail over IMAP with an app-specific password, including listing mailboxes, browsing and searching messages, and reading message bodies and attachment filenames. All operations are read-only, so messages remain unread and cannot be sent, deleted, moved, or altered.
      4
      MIT