icloud-calendar-mcp

안정적이고 가벼운 Apple iCloud Calendar MCP 서버입니다. 순수 TypeScript/Node.js로 작성되었으며, CalDAV를 통해 직접 iCloud에 연결됩니다. Java, Python, Go, AppleScript, macOS 또는 Calendar.app에 의존하지 않습니다.

English summary: A production-oriented, cross-platform TypeScript MCP server for Apple iCloud Calendar. It provides guarded CalDAV CRUD, persistent opaque handles, idempotent writes, ETag concurrency control, recurrence expansion, stdio and secured Streamable HTTP transports.

설치

Node.js 20 이상이 필요합니다. Apple의 '앱 전용 비밀번호'를 사용해야 하며, Apple 계정의 기본 비밀번호는 사용하지 마십시오.

npx icloud-calendar-mcp

앱 전용 비밀번호 생성: account.apple.com에 로그인하여 '로그인 및 보안' → '앱 전용 비밀번호'로 이동합니다. Apple은 동시에 활성화할 수 있는 앱 전용 비밀번호 수를 제한할 수 있습니다. 비밀번호를 취소하면 이 서비스는 AUTH_FAILED 오류를 반환합니다.

stdio 클라이언트 설정:

{
  "mcpServers": {
    "icloud-calendar": {
      "command": "npx",
      "args": ["-y", "icloud-calendar-mcp"],
      "env": {
        "ICLOUD_USERNAME": "you@example.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

stdout은 JSON-RPC에만 사용되며, 모든 로그는 stderr로 기록됩니다.

Related MCP server: Chronos MCP

도구 및 MCP 콘텐츠

도구는 structuredContent와 텍스트 JSON을 동시에 반환하며, read-only/destructive/idempotent/open-world 애너테이션을 선언합니다. 리소스: calendar://calendars. 명시적 사용자 템플릿 프롬프트: schedule_event, reschedule_event, find_conflicts; 이 프롬프트는 사용자를 대신하여 일정 결정을 자동으로 내리지 않습니다.

이벤트는 시간 지정/종일, 제목, 설명, 장소, URL, RRULE, DISPLAY 알람 및 참석자를 지원합니다. 참석자 필드는 iCloud 및 캘린더 공유 권한에 의해 제한되며, 이 서비스는 'ATTENDEE' 쓰기를 성공적으로 초대가 전송된 것으로 잘못 보고하지 않습니다.

시간 및 반복 이벤트 의미

• 시간 지정 이벤트 입력은 ISO 8601 시간과 IANA timezone을 제공해야 함; 출력도 명시적으로 시간대를 반환합니다.

• 종일 이벤트 start/end는 YYYY-MM-DD를 사용하며, end는 이벤트에 포함되지 않습니다. 예를 들어 8월 18일 종일 이벤트는 start=2026-08-18, end=2026-08-19입니다.

• iCalendar는 ical.js를 사용하여 구축 및 구문 분석하며, 사용자 필드를 문자열로 연결하지 않습니다. 테스트는 DST, UTC 및 종일 경계를 포함합니다.

• list_events는 CalDAV calendar-data/expand 요청을 통해 RRULE 발생을 확장합니다.

• whole_series는 업데이트/삭제를 지원합니다. single_occurrence, this_and_future는 iCloud의 recurrence exception 기능이 검증되지 않은 경우 UNSUPPORTED_OPERATION을 반환하며, 절대 조용히 전체 시리즈로 변경하지 않습니다.

HTTP 모드

HTTP는 기본적으로 비활성화되어 있습니다. 활성화하면 loopback만 수신하며, bearer 토큰은 최소 24자 이상이어야 합니다:

ICLOUD_MCP_TRANSPORT=http \
ICLOUD_MCP_HTTP_TOKEN='replace-with-a-long-random-token' \
ICLOUD_MCP_HTTP_PORT=3000 \
npx icloud-calendar-mcp

• MCP 엔드포인트: POST /mcp

• 상태 확인: GET /healthz (Apple에 접근하지 않으며, 계정 상태를 노출하지 않음)

• 강제 bearer 토큰; 고정 Host allowlist; Origin 기본적으로 모두 거부; 기본 요청 상한 1 MiB; 로컬 읽기/쓰기 속도 제한; 시간 초과 및 보안 응답 헤더 경계.

• ICLOUD_MCP_CONFIG=/absolute/path/config.json을 통해 안정적인 매개변수 설정 (예: allowedHosts, allowedOrigins, timeoutMs, maxEvents, 읽기/쓰기 속도 제한 및 요청 상한). 자격 증명은 이 파일에 포함할 수 없습니다.

전체 설정 계약은 docs/tool-contracts.md에서, 보안 모델은 docs/security.md에서 확인할 수 있습니다.

안정성

• create의 UID는 request_id의 안정적인 SHA-256 파생 값; 중복 요청이 두 번째 이벤트를 생성하지 않습니다.

• create는 If-None-Match: *를 사용하고, update/delete는 읽은 ETag의 If-Match를 사용합니다.

• journal은 원자적 rename을 사용하여 사용자 데이터 디렉터리(기본값 ~/.icloud-caldav-mcp/journal.json, 권한 엄격)에 기록되며, 요청 재생(replay) 및 opaque handle을 저장합니다.

• 429/5xx/네트워크 일시적 오류는 지터가 있는 지수 백오프를 사용하고 Retry-After를 존중합니다. 응답 ETag가 없는 경우 read-after-write 가시성 폴링을 수행합니다.

• 안정적인 오류 코드: AUTH_FAILED, CALENDAR_NOT_FOUND, EVENT_NOT_FOUND, ETAG_CONFLICT, INVALID_EVENT, RATE_LIMITED, TEMPORARY_UNAVAILABLE, UNSUPPORTED_OPERATION.

개발 및 실제 계정 smoke 테스트

pnpm install
pnpm check
pnpm pack

사용자에게 영향을 미치는 변경 사항은 pnpm changeset을 사용하여 기록합니다. main에 푸시하면 Changesets가 자동으로 Release PR을 생성하거나 업데이트합니다. 해당 PR을 병합한 후 npm Trusted Publishing을 통해 provenance와 함께 자동으로 게시됩니다. 처음 활성화하기 전에 npm 패키지 설정에서 .github/workflows/release.yml을 Trusted Publisher로 구성해야 합니다.

CI는 fake adapter/HTTP fixtures를 사용하며, 실제 Apple 계정이 필요하지 않습니다. 선택적 실제 테스트는 로컬에서 ICLOUD_USERNAME과 ICLOUD_APP_PASSWORD를 명시적으로 제공한 후에만 실행됩니다: pnpm smoke:icloud. 현재 smoke 테스트 스위트는 기본적으로 쓰기 작업을 건너뜁니다. 첫 실제 검증은 전용 테스트 캘린더를 사용하여 수동으로 discovery/list/create/update/delete/recurrence exception 동작을 확인하는 것이 좋습니다.

문제 해결: 401/403은 앱 전용 비밀번호를 확인하십시오. 412는 ETag 동시성 충돌을 의미하므로 list_events/get_event를 다시 실행하십시오. 429는 대기 후 재시도하십시오. 알 수 없는 handle은 journal이 삭제되었거나 데이터 디렉터리가 변경되었음을 나타냅니다. 전체 CalDAV URL, Authorization 또는 이벤트 본문을 이슈에 붙여넣지 마십시오.

라이선스

MIT. 독립적인 독창적인 코드로 구현되었습니다. 공개 프로젝트는 인터페이스 및 아키텍처 차이 연구에만 사용되며, 타사 소스 코드를 복사하지 않았습니다.