Apple Calendar MCP

Apple Calendar MCP는 AI 클라이언트에 iCloud Calendar 계정 하나에 대한 원격 읽기 및 쓰기 액세스를 제공합니다. 이 서버는 Cloudflare에서 무상태 TypeScript Worker로 실행되며, Apple 기기가 온라인 상태일 필요가 없습니다.

배포 하나는 Apple 계정 하나에 연결됩니다. 다중 사용자 캘린더 서비스가 아닙니다.

배포 전 준비 사항

필요한 것:

• Cloudflare 계정.

• 이중 인증이 설정된 Apple Account.

• 원격 HTTPS 서버와 OAuth를 지원하는 MCP 클라이언트.

• IANA 시간대 이름 (예: America/New_York).

Apple 및 Cloudflare 설정 페이지는 직접 여세요. 에이전트가 안내하고 결과를 확인할 수는 있지만, 비밀번호를 받거나 입력해서는 안 됩니다.

[!WARNING] Apple Account 비밀번호, Apple 앱별 암호, 승인 비밀번호를 채팅, 소스 제어 저장소, 로그, 이슈에 붙여넣지 마세요.

Related MCP server: calendar-app-mcp

Apple 앱별 암호 만들기

1. account.apple.com을 열고 로그인합니다.

2. 로그인 및 보안 > 앱별 암호를 선택합니다.

3. 앱별 암호 생성을 선택합니다.

4. Apple Calendar MCP 같은 알아보기 쉬운 이름을 지정합니다.

5. Cloudflare가 요청할 때까지 생성된 값을 Apple 페이지에 보관해 둡니다.

Apple은 앱별 암호에 이중 인증을 요구합니다. 최대 25개의 활성 암호를 가질 수 있으며, 하나 또는 전체를 폐기할 수 있습니다. 기본 Apple Account 비밀번호를 변경하거나 재설정하면 모든 앱별 암호가 폐기됩니다. Apple의 앱별 암호 지침을 참조하세요.

[!WARNING] Apple 앱별 암호는 이 MCP가 클라이언트에 표시하는 캘린더 권한보다 범위가 넓습니다. Worker는 허용 목록에 등록된 iCloud CalDAV 호스트로만 제한되지만, Apple은 캘린더 전용 앱별 암호를 발급하지 않습니다.

Cloudflare에 배포

1. 이 페이지 상단의 Cloudflare에 배포를 선택합니다.

2. Cloudflare에 로그인하고 배포 양식을 따릅니다.

3. Cloudflare가 요청하면 세 가지 비밀 값을 입력합니다.

   • ICLOUD_USERNAME: Apple Account 및 iCloud Calendar에 사용하는 전체 이메일 주소.

   • ICLOUD_APP_PASSWORD: Apple이 생성한 앱별 암호. 그대로 정확히 보존하세요.

   • APPROVAL_PASSWORD: 새 MCP 클라이언트 승인을 보호하는 별도의 고유 암호. Apple 비밀번호 중 하나를 재사용하지 마세요.

4. Worker 배포가 끝날 때까지 기다립니다.

5. Workers & Pages를 열고 Worker를 선택한 다음 설정을 선택하고 변수 및 비밀을 찾습니다.

6. CALENDAR_TIME_ZONE을 UTC에서 IANA 시간대 이름으로 변경한 다음 설정을 배포합니다.

7. 다음 형식으로 엔드포인트를 복사합니다: https://<worker-name>.<account-subdomain>.workers.dev/mcp.

Cloudflare는 세 가지 비밀 값을 암호화된 Worker 비밀로 저장합니다. 배포 양식은 이 값들을 생성된 저장소나 로컬 .dev.vars 파일에 기록하지 않습니다.

비밀 값을 건너뛰었거나 교체해야 한다면 Workers & Pages를 열고 Worker를 선택한 다음 설정을 선택하고 변수 및 비밀을 찾아 값을 비밀로 추가하거나 편집한 후 배포를 선택합니다.

Cloudflare는 OAUTH_KV 네임스페이스를 자동으로 프로비저닝합니다. wrangler.jsonc에 KV ID를 추가하지 마세요.

MCP 클라이언트 연결

1. 배포된 /mcp 엔드포인트를 사용자 지정 원격 MCP 서버 또는 앱으로 추가합니다.

2. 연결을 선택합니다. 클라이언트가 OAuth를 발견하고 Apple Calendar MCP 승인 페이지를 열어야 합니다.

3. 클라이언트 이름과 요청된 권한을 확인합니다.

4. APPROVAL_PASSWORD를 입력하고 허용 및 돌아가기를 선택합니다. 페이지가 원하는 수준 이상의 액세스를 요청하면 취소를 선택합니다.

5. 클라이언트가 연결 완료를 보고할 때까지 기다립니다. 완료 후에도 브라우저 탭이 열려 있으면 닫습니다.

6. 클라이언트의 도구를 새로 고치거나 다시 스캔합니다. 클라이언트는 연결 또는 서버 업데이트 후 도구 카탈로그를 캐시할 수 있습니다.

Claude에 대해서는 원격 MCP와 사용자 지정 커넥터 사용을 참조하세요. ChatGPT에 대해서는 ChatGPT의 개발자 모드 및 전체 MCP 커넥터를 참조하세요.

승인 페이지에서는 두 가지 권한을 제공합니다.

• 캘린더 및 이벤트 읽기는 calendar:read를 부여하고 7개의 읽기 도구를 노출합니다.

• 캘린더 및 이벤트 읽기 및 편집은 calendar:read calendar:write를 부여하고 4개의 변경 도구를 추가합니다.

권한을 변경하려면 다시 인증하고 도구 카탈로그를 새로 고쳐야 합니다. 서버 업데이트가 기존 읽기 전용 권한에 쓰기 도구를 추가하지는 않습니다.

[!WARNING] 참석자 또는 초대장이 관련된 쓰기 작업은 다른 사람에게 이메일이나 알림을 보낼 수 있습니다.

연결 확인

먼저 읽기 액세스를 확인합니다.

1. calendar_get_profile을 호출합니다. Apple Account ID와 시간대를 확인합니다.

2. calendar_list_calendars를 호출합니다. 예상한 캘린더 이름이 표시되는지 확인합니다.

3. 읽기 전용 액세스를 승인했다면 클라이언트에 변경 도구가 표시되지 않는지 확인합니다.

배포, 비밀 입력, OAuth 연결, 캘린더 읽기 성공은 별개의 상태입니다. 캘린더 읽기가 성공했다는 것은 Apple 자격 증명이 작동한다는 증거입니다.

쓰기 액세스를 확인하려면 먼저 Apple Calendar에 빈 임시 캘린더를 만드세요. 사용자가 확인한 후에만 에이전트에게 이 제한된 테스트를 실행하도록 요청하세요.

1. 참석자, 반복, 알림이 없고 고유한 제목을 가진 미래 이벤트 하나를 만듭니다.

2. 이벤트를 읽고 현재 ETag를 보관합니다.

3. 해당 ETag를 사용하여 제목만 변경합니다.

4. 이벤트를 다시 읽고 반환된 ETag를 사용하여 삭제합니다.

5. 이벤트가 없는지 확인합니다.

정리가 실패하면 정확한 캘린더, 제목, 시간을 기록해 두어 직접 이벤트를 제거할 수 있게 하세요. 기본 캘린더에서는 쓰기 테스트를 하지 마세요.

에이전트에게 에이전트와 함께 Apple Calendar MCP 설정의 제한된 절차를 줄 수도 있습니다.

도구

업데이트, 삭제, 초대 응답 도구는 최신 ETag가 필요합니다. 반복 발생 변경에는 검색이 반환한 원래 recurrenceId도 필요합니다.

시간 입력은 Z 또는 명시적 오프셋이 있는 RFC 3339 타임스탬프를 사용합니다. 클라이언트는 timeZone을 생략할 수 있습니다. 생성 시 캘린더에 게시된 IANA 시간대를 사용하고, 그다음 CALENDAR_TIME_ZONE을 사용합니다. 시간 출력에는 UTC 및 로컬 값이 포함됩니다.

location은 표시되는 Calendar 필드입니다. structuredLocation은 제목, 주소, 위도, 경도, 반경을 추가할 수 있습니다. 확인된 좌표는 Apple Calendar의 지도 미리보기를 활성화합니다. 좌표를 추측하지 마세요.

description은 Calendar 메모에 매핑됩니다. url은 이벤트 URL 필드에 매핑됩니다. MCP는 관련 없는 변경 중에 지원되지 않는 첨부 파일과 알람 유형을 보존하지만, 첨부 파일을 업로드, 다운로드, 수정하지 않습니다. 원시 ICS를 가져오지 않습니다.

사용자 지정 도메인 사용

기본 workers.dev 엔드포인트는 호스트 이름 구성이 필요 없습니다. 사용자 지정 도메인에는 명시적 허용 목록 설정 하나가 필요합니다.

1. Cloudflare에서 Worker를 엽니다.

2. 설정 > 도메인 및 경로 > 추가 > 사용자 지정 도메인을 선택하고 호스트 이름을 추가합니다.

3. 변수 및 비밀에서 MCP_HOSTNAME을 일반 텍스트 변수로 추가합니다. calendar.example.com 같은 호스트 이름만 입력합니다. https://, 경로, 포트, 자격 증명을 포함하지 마세요.

4. 설정을 배포합니다.

5. https://<custom-host>/mcp에서 클라이언트를 다시 연결하고 인증도 다시 완료합니다.

호스트 이름은 OAuth ID의 일부입니다. workers.dev에 대해 발급된 토큰은 사용자 지정 원본으로 이동하지 않습니다.

Cloudflare Access 추가

기본 제공 승인 비밀번호는 기본 권한 부여 보호 장치입니다. Cloudflare Access는 선택적인 심층 방어입니다.

Access를 추가하는 경우 <hostname>/authorize만 보호하세요. /mcp, /.well-known/*, /oauth/token, /oauth/register는 MCP 클라이언트가 접근할 수 있게 두세요. Access가 /authorize를 보호하는지 확인한 후 EXTERNAL_AUTHORIZATION=true를 일반 텍스트 Worker 변수로 추가하세요.

[!WARNING] 외부 보호 장치가 /authorize를 보호한 후에만 EXTERNAL_AUTHORIZATION=true를 설정하세요. 이 설정은 외부 보호 장치가 활성 상태임을 선언합니다.

보안

Worker는 런타임에 Apple 사용자 이름과 앱별 암호를 받습니다. Cloudflare 계정, 배포된 소스, Apple, 그리고 연결된 모든 MCP 클라이언트를 신뢰해야 합니다. Cloudflare 계정에 대한 액세스를 제한하고 신뢰하는 클라이언트만 연결하세요.

APPROVAL_PASSWORD는 새 승인을 보호합니다. 승인 라우트는 이 암호가 구성되어 있거나 EXTERNAL_AUTHORIZATION이 검증된 외부 보호 장치를 선언하지 않는 한 기본적으로 닫힙니다(fail closed). 보호 장치를 통과하는 사람은 누구나 구성된 Apple 계정에 대해 클라이언트를 승인할 수 있습니다.

[!WARNING] APPROVAL_PASSWORD를 교체해도 이미 발급된 OAuth 토큰은 폐기되지 않습니다.

Cloudflare의 OAuth 공급자는 액세스 토큰, 리프레시 토큰, 권한 부여 코드, 등록된 클라이언트 비밀을 해시로 저장합니다. 권한 부여 속성은 암호화됩니다. 클라이언트 이름과 권한 부여 메타데이터는 저장소에 계속 표시되므로 비밀을 포함해서는 안 됩니다. 공급자의 KV 저장소 및 정리 문서를 참조하세요.

Worker는 허용 목록에 등록된 iCloud CalDAV 호스트에만 HTTPS로 Apple 자격 증명을 전송합니다. 도구 인수는 업스트림 호스트를 선택할 수 없습니다. 오류는 자격 증명과 유사한 값을 제거합니다. Worker는 도구 인수나 이벤트 페이로드를 기록하지 않습니다.

도구 결과에는 제목, 메모, 위치, 참석자, URL이 포함될 수 있습니다. MCP 클라이언트는 자체 제품 및 워크스페이스 정책에 따라 이 데이터를 보관할 수 있습니다.

쓰기 액세스는 이벤트 생성, 변경, 삭제, 초대 응답을 포함합니다. ETag는 더 새로운 이벤트를 덮어쓰는 것을 방지하지만, 의도하지 않은 쓰기를 무해하게 만들 수는 없습니다. 관련 없는 업데이트는 가능할 때 지원되지 않는 Apple 속성을 보존합니다.

이 정식 저장소 또는 변경 내용을 검토한 포크에서 배포하세요. 원격 MCP 서버는 소유자가 새 코드를 배포할 때 도구 카탈로그를 변경할 수 있습니다.

침해가 의심되면 이전 Apple 앱별 암호를 먼저 해지하세요. 그런 다음 새 암호로 교체하고 접근을 확인하세요. 이로 인해 짧은 가동 중단이 발생합니다.

문제 해결

• 401 또는 iCloud 암호 거부는 일반적으로 앱별 암호가 없거나 해지되었음을 의미합니다. Apple과 Cloudflare에서 앱별 암호를 만들거나 교체하세요. 채팅에 붙여넣지 마세요.

• 쓰기 도구가 없다면 일반적으로 클라이언트에 읽기 전용 권한만 있거나 도구 카탈로그가 캐시되어 있기 때문입니다. 도구를 새로고침한 다음, 필요하면 연결을 끊고 다시 인증하세요.

• 사용자 지정 도메인이 /mcp를 거부한다면 일반적으로 MCP_HOSTNAME이 누락되었거나 유효하지 않은 경우입니다. 정확한 호스트 이름을 설정하고 다시 배포하세요.

• 승인 페이지가 기본 거부로 실패하는 경우는 APPROVAL_PASSWORD도 선언된 외부 보호 장치도 없을 때입니다. /authorize에서 Cloudflare Access를 이미 확인하지 않았다면 승인 비밀값을 추가하세요.

로컬 개발

bun install
cp .dev.vars.example .dev.vars
bun run test
bun run typecheck
bun run cloudflare:check

.dev.vars는 로컬에 보관하세요. bun run deploy로 배포하세요.

라이선스

MIT