CalDAV MCP Server
CalDAV MCP 서버
CalDAV MCP 서버는 iCloud 캘린더 이벤트를 관리하기 위한 Model Context Protocol 서버로, 단일 이벤트에 여러 개의 VALARM 알림을 기본 지원합니다.
iCloud 캘린더는 첫 번째 릴리스에서 공식적으로 지원되고 수동 검증된 유일한 제공자입니다. 이 서버는 stdio 또는 Streamable HTTP를 지원하는 모든 MCP 클라이언트에서 작동합니다.
이 독립 프로젝트는 Apple Inc.와 제휴, 승인, 후원 또는 보증 관계가 아닙니다. Apple 및 iCloud는 해당 소유자의 상표입니다.
목차
Related MCP server: DAV MCP Server
소개
이 서버는 구성된 하나의 계정을 CalDAV를 통해 iCloud에 연결합니다. 계정의 캘린더를 검색하고 정규화된 읽기 및 쓰기 작업을 MCP를 통해 노출합니다.
업데이트는 알 수 없는 속성, Apple 확장, VTIMEZONE, 반복 예외, 패치에서 생략된 알림을 포함한 완전한 iCalendar 리소스를 보존합니다. 쓰기는 CalDAV 파일 이름이 이벤트 UID와 일치한다고 가정하는 대신 불투명한 리소스 식별자와 ETag를 사용합니다.
캘린더 리소스는 메모리에서 처리됩니다. 이 서버는 원격 측정이나 애플리케이션 데이터베이스가 없으며, 원시 iCalendar는 명시적으로 요청된 경우에만 반환됩니다.
기능
구성된 iCloud 계정에서 사용 가능한 캘린더를 검색합니다.
반개방 시간 범위의 이벤트를 나열하고 반복 발생을 확장합니다.
시간 지정, 종일, 반복 이벤트를 생성합니다.
이벤트당 0개, 1개 또는 여러 개의 표시 알림을 지원합니다.
iCloud 캘린더가 기대하는 Apple 알림 확장을 생성합니다.
불투명한 리소스 ID 또는 캘린더 ID와 UID 조합으로 이벤트를 읽습니다.
생략되거나 알 수 없는 iCalendar 데이터를 보존하면서 부분 업데이트를 적용합니다.
업데이트 및 삭제 시 낙관적 동시성을 위해 ETag를 사용합니다.
전체 시리즈를 변경하는 대신 개별 반복 변경을 거부합니다.
로그와 오류에서 자격 증명, 원시 캘린더 콘텐츠, CalDAV 경로를 삭제합니다.
읽기 전용 루트 파일시스템 구성으로 비루트 컨테이너로 실행됩니다.
stdio및 Streamable HTTP MCP 전송을 지원합니다.
MCP 도구
list_calendars
구성된 계정에서 검색된 캘린더를 나열합니다. 각 결과에는 불투명한 calendar_id, 표시 이름, 설명, 시간대, 최선 노력 쓰기 상태가 포함됩니다.
list_events
반개방 구간의 이벤트를 나열하고 반복 발생을 확장합니다. 최대 범위는 366일, 기본 페이지 크기는 100, 최대 페이지 크기는 500입니다. 결과는 결정적 시간순으로 정렬됩니다. 페이지네이션 커서는 불투명하며, 순회 중 이벤트가 수정되면 스냅샷을 나타내지 않습니다.
입력 예시:
{
"calendar_id": "opaque-calendar-id",
"start": "2026-09-01T00:00:00Z",
"end": "2026-10-01T00:00:00Z",
"timezone": "Europe/Berlin",
"limit": 100
}get_event
resource_id 또는 calendar_id와 UID 쌍으로 이벤트를 읽습니다. 원시 iCalendar는 기본적으로 제외되며, 통제된 진단을 위해 include_raw_ical: true로 요청할 수 있습니다.
create_event
이벤트를 생성하고 서버가 저장한 표현을 다시 읽습니다.
알림 두 개가 있는 시간 지정 이벤트:
{
"calendar_id": "opaque-calendar-id",
"summary": "Buy Shinkansen tickets",
"start": {
"date_time": "2026-09-06T03:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-06T03:30:00+02:00",
"timezone": "Europe/Berlin"
},
"description": "Smart-EX",
"location": null,
"alarms": [
{ "minutes_before": 1440, "action": "DISPLAY" },
{ "minutes_before": 0, "action": "DISPLAY" }
],
"rrule": null
}종료일이 배타적인 종일 이벤트:
{
"calendar_id": "opaque-calendar-id",
"summary": "Trip",
"start": { "date": "2026-09-06" },
"end": { "date": "2026-09-08" },
"alarms": []
}반복 이벤트는 RRULE: 접두사 없이 RFC 5545 규칙을 허용합니다:
{
"calendar_id": "opaque-calendar-id",
"summary": "Weekly planning",
"start": {
"date_time": "2026-09-07T09:00:00+02:00",
"timezone": "Europe/Berlin"
},
"end": {
"date_time": "2026-09-07T09:30:00+02:00",
"timezone": "Europe/Berlin"
},
"rrule": "FREQ=WEEKLY;BYDAY=MO;COUNT=10"
}update_event
이벤트 또는 전체 반복 시리즈를 패치합니다. 생략된 필드는 보존되고, null은 nullable 필드를 제거하며, alarms: []는 모든 알림을 제거합니다. 선택적 expected_etag는 최신 서버 버전을 덮어쓰는 것을 방지합니다.
delete_event
이벤트 또는 전체 반복 시리즈를 삭제하며, 선택적으로 관찰된 ETag를 요구합니다. 단일 확장 발생 삭제는 현재 릴리스에서 지원되지 않습니다.
기술 스택
엄격한 프로젝트 규칙을 사용하는 TypeScript
설치
사전 요구 사항
캘린더가 활성화된 iCloud 계정.
Apple 계정에 2단계 인증이 활성화되어 있어야 합니다.
컨테이너 배포를 위한 Docker 및 Docker Compose, 또는 로컬 설치를 위한 Node.js 24+ 및 pnpm.
Docker Compose
권장 설치는 게시된 멀티 아키텍처 이미지를 사용합니다:
ghcr.io/lukegskw/caldav-mcp:latestCompose 예제를 다운로드합니다:
curl -O https://raw.githubusercontent.com/lukegskw/caldav-mcp/main/compose.example.yamlApple 계정 이메일과 앱별 암호를 제공한 후 서비스를 시작합니다:
export CALDAV_USERNAME='user@example.com'
export CALDAV_PASSWORD='xxxx-xxxx-xxxx-xxxx'
docker compose -f compose.example.yaml up -d다른 호스트 포트를 게시하려면 다음을 설정합니다:
export CALDAV_MCP_PUBLISHED_PORT=18100
docker compose -f compose.example.yaml up -dlatest 태그는 기본 브랜치의 가장 최근 성공적인 빌드를 따릅니다. 통제된 배포 또는 롤백을 위해 Compose 파일에서 게시된 버전 또는 변경 불가능한 sha-* 태그로 교체합니다.
Streamable HTTP 엔드포인트는 다음에서 사용할 수 있습니다:
http://<host>:8100/mcp호스트 포트는 컨테이너 내부의 포트 8100을 변경하지 않고 변경될 수 있습니다. 영구 볼륨은 필요하지 않습니다. 캘린더 데이터는 iCloud에 유지됩니다.
Docker run
동일한 강화된 컨테이너 구성을 직접 시작할 수 있습니다:
docker run -d \
--name caldav-mcp \
--restart unless-stopped \
--read-only \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:size=16m,mode=1777 \
-e CALDAV_PROVIDER=icloud \
-e CALDAV_USERNAME \
-e CALDAV_PASSWORD \
-e CALDAV_MCP_TRANSPORT=streamable-http \
-e CALDAV_MCP_HOST=0.0.0.0 \
-p 8100:8100 \
ghcr.io/lukegskw/caldav-mcp:latest소스에서 컨테이너 빌드
로컬 빌드는 선택 사항입니다. 컨테이너 빌드를 수정하거나 감사할 필요가 없다면 게시된 이미지를 선호합니다.
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
docker buildx build --load -t caldav-mcp:local .로컬 Node.js 설치
git clone https://github.com/lukegskw/caldav-mcp.git
cd caldav-mcp
pnpm install --frozen-lockfile
cp .env.example .env
pnpm build
pnpm start -- --transport stdiostdio 모드에서 stdout은 MCP 메시지 전용으로 예약됩니다. Streamable HTTP를 로컬에서 실행하려면:
CALDAV_MCP_TRANSPORT=streamable-http pnpm start구성
모든 설정은 CALDAV_ 또는 CALDAV_MCP_ 접두사를 사용합니다.
변수 | 필수 | 기본값 | 설명 |
| 아니요 |
| 제공자 정책. iCloud가 지원되는 프로필입니다. |
| 아니요 |
| CalDAV 검색 URL. |
| 예 | 없음 | Apple 계정 이메일. |
| 예 | 없음 | 앱별 암호. 계정 암호가 아닙니다. |
| 아니요 |
|
|
| 아니요 |
| HTTP 바인드 주소. |
| 아니요 |
| HTTP 수신 포트. |
| 아니요 |
| 애플리케이션 로그 수준. |
| 아니요 |
| CalDAV 요청 시간 제한. |
코어는 Apple 확장을 공유 iCalendar 구현에서 분리하기 위해 실험적인 generic 제공자 정책과 구성 가능한 URL을 유지합니다. 현재 다른 제공자와의 호환성은 주장되지 않습니다.
비밀은 배포 플랫폼 또는 환경을 통해 제공되어야 합니다. .env를 커밋하거나, MCP 도구 인수로 자격 증명을 전달하거나, 진단 보고서에 포함하지 마십시오.
MCP 클라이언트 설정
Streamable HTTP 서버 정의를 허용하는 모든 MCP 클라이언트에 대해 URL을 구성합니다:
mcp_servers:
caldav:
url: http://<host>:8100/mcp클라이언트가 Compose 네트워크를 공유하는 경우 서비스 이름과 내부 포트를 사용합니다:
mcp_servers:
caldav:
url: http://caldav-mcp:8100/mcp로컬 stdio 서버를 시작하는 클라이언트의 경우 필수 환경 변수와 함께 node /absolute/path/to/caldav-mcp/dist/main.js를 실행하도록 명령을 구성합니다.
Claude Desktop (Docker, stdio)
Claude Desktop은 로컬 stdio 서버를 하위 프로세스로 시작합니다. 게시된 컨테이너를 이 방식으로 실행하면 앱별 암호가 클라이언트 머신에 유지되고 네트워크 포트가 열리지 않으며, 이는 제한 사항의 전송 지침과 일치합니다.
claude_desktop_config.json에 서버를 추가합니다:
{
"mcpServers": {
"icloud-calendar": {
"command": "/absolute/path/to/docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/absolute/path/to/caldav-mcp.env",
"-e",
"CALDAV_PROVIDER=icloud",
"-e",
"CALDAV_MCP_TRANSPORT=stdio",
"ghcr.io/lukegskw/caldav-mcp@sha256:<digest>"
]
}
}
}-i는 필수입니다. 연결된 stdin이 없으면 클라이언트는 컨테이너와 MCP 통신을 할 수 없습니다. --rm은 클라이언트가 서버를 중지하면 컨테이너를 제거합니다.
-e 대신 --env-file을 통해 자격 증명을 제공합니다. docker run에 전달된 인수는 호스트 프로세스 목록에 표시되지만 env 파일의 내용은 표시되지 않습니다. 파일에는 구성에 설명된 변수가 포함됩니다:
CALDAV_USERNAME=user@example.com
CALDAV_PASSWORD=xxxx-xxxx-xxxx-xxxx클라이언트를 다시 시작할 때 다른 버전이 조용히 시작되지 않도록 latest 대신 다이제스트로 이미지를 고정합니다:
docker pull ghcr.io/lukegskw/caldav-mcp:latest
docker images --digests ghcr.io/lukegskw/caldav-mcp구성 파일을 편집한 후 Claude Desktop을 완전히 다시 시작합니다.
Windows
설정 -> 개발자 -> 구성 편집을 통해 구성 파일을 만들고 찾습니다. 경로를 가정하지 마십시오. Claude Desktop이 Microsoft Store에서 설치된 경우 Windows는 %APPDATA%\Claude를 패키지 컨테이너로 리디렉션하며 파일은 다음 위치에 있습니다:
%LOCALAPPDATA%\Packages\Claude_<package-id>\LocalCache\Roaming\Claude\claude_desktop_config.json이 경우 dir %APPDATA%\Claude는 아무것도 보고하지 않습니다. 서버 로그는 구성 파일 옆의 logs\mcp-server-<server-name>.log에 기록됩니다.
패키지 컨테이너 내부의 PATH가 신뢰할 수 없으므로 docker.exe의 절대 경로를 사용합니다. where docker가 이를 출력하며, 일반적으로 C:\Program Files\Docker\Docker\resources\bin\docker.exe입니다. JSON에서는 백슬래시를 이스케이프해야 합니다.
구성 형식은 MCP 클라이언트마다 다릅니다. 정확한 스키마는 클라이언트 문서를 참조하고 서버 정의를 변경한 후 다시 로드하거나 재시작합니다.
검증
컨테이너 상태와 로그를 확인합니다:
docker compose -f compose.example.yaml ps
docker compose -f compose.example.yaml logs caldav-mcp컨테이너는 healthy를 보고해야 합니다. TCP 상태 확인은 서버 프로세스를 검증하며 iCloud 자격 증명은 검증하지 않습니다.
저장소 검증 스위트를 실행합니다:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build마지막으로 MCP 클라이언트로 연결하여 여섯 개의 도구가 모두 나열되는지 확인합니다. 릴리스 전에 테스트 캘린더를 대상으로 전용 iCloud 수동 검증을 실행합니다.
제한 사항
서버 프로세스 또는 컨테이너당 하나의 iCloud 계정이 구성됩니다.
Streamable HTTP 엔드포인트는 현재 릴리스에서 인증이 없습니다. 신뢰할 수 있는 LAN, VPN 또는 사설 컨테이너 네트워크로 제한하고 인터넷에 직접 노출하지 마십시오.
개별 반복 발생은 읽기 전용입니다. 전체 시리즈 업데이트 및 삭제는 지원됩니다.
ACTION:DISPLAY알림만 생성됩니다.개별 iCalendar 리소스는 5MiB로 제한됩니다.
이벤트 목록 범위는 366일, 페이지는 500개 결과로 제한됩니다.
이벤트에는 최대 20개의 알림이 포함될 수 있습니다.
참석자 일정 관리는 현재 범위를 벗어납니다.
iCloud 이외의 제공자는 공식적으로 지원되지 않습니다.
검색, 인증, ETag 및 Apple 확장 지침은 문제 해결을 참조하십시오. 보안 문제를 보고하거나 진단을 첨부하기 전에 SECURITY.md를 검토하십시오.
기여
기여를 환영합니다. 풀 리퀘스트를 열기 전에:
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t caldav-mcp:test .CalDAV 쓰기 또는 iCalendar 직렬화 변경은 ETag 검사, 불투명한 리소스 경계, 알 수 없는 속성, 반복 예외, 패치에서 생략된 알림을 보존해야 합니다. TypeScript 변경은 계속해서 .codex/rules/typescript.md의 규칙을 충족해야 합니다.
라이선스
MIT. LICENSE를 참조하십시오.
Available Tools
6 toolscreate_eventCreate calendar eventA
Create a new event in a writable iCloud calendar and return the stored representation; existing events are not changed. Use list_calendars first to obtain calendar_id, and use update_event when the event already exists. Timed values require matching offsets and timezones, all-day end dates are exclusive, recurrence rules omit the RRULE: prefix, and travel_minutes sets Apple Calendar travel time for timed events.
Inputs: end (required), start (required), summary (required), calendar_id (required), +5 more. Returns: end, uid, etag, href, +13 more
delete_eventDelete calendar eventADestructiveIdempotent
Permanently delete an event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid, and supply expected_etag when available to prevent deleting a concurrently changed event.
Inputs: uid, calendar_id, resource_id, expected_etag. Returns: deleted, resource_id
get_eventGet calendar eventARead-onlyIdempotent
Read one event by resource_id, preferably from a previous result, or by the calendar_id and uid pair. Use list_events for range searches. Request raw iCalendar only for controlled diagnostics because it may contain sensitive calendar data.
Inputs: uid, calendar_id, resource_id, include_raw_ical. Returns: end, uid, etag, href, +13 more
list_calendarsList calendarsARead-onlyIdempotent
List calendars available in the configured iCloud account. Use this first to obtain the opaque calendar_id required by list_events and create_event; writable is a best-effort capability indicator.
Inputs: no named parameters. Returns: calendars
list_eventsList calendar eventsARead-onlyIdempotent
List events that overlap the start-inclusive, end-exclusive interval and expand recurring series into occurrences, across at most 366 days. Use list_calendars first to obtain calendar_id and use get_event instead for one known event. Continue with next_cursor and unchanged query filters when more results are available.
Inputs: end (required), start (required), calendar_id (required), limit, +2 more. Returns: events, next_cursor
update_eventUpdate calendar eventADestructive
Modify an existing event or entire recurring series; individual expanded occurrences are not supported. Target it by resource_id or by calendar_id with uid. Omitted patch fields are preserved, null clears nullable fields, an empty alarms array removes alarms, and expected_etag can prevent a stale write.
Inputs: patch (required), uid, calendar_id, resource_id, +1 more. Returns: end, uid, etag, href, +13 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct action on a distinct resource: create/list/get/update/delete events plus list calendars. The descriptions explicitly clarify boundaries, such as list_events vs get_event and update vs create.
All tool names follow a consistent verb_noun snake_case pattern: create_event, list_events, get_event, update_event, delete_event, list_calendars.
Six tools are well-scoped for a CalDAV server: one discovery tool and a complete event CRUD set. No tool appears redundant or trivial.
The surface covers full event lifecycle plus calendar discovery, which is the core domain. Minor gaps exist around calendar-level operations and individual recurring-occurrence edits, though these are documented limitations rather than dead ends.
Maintenance
Related MCP Connectors
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Model Context Protocol server for todo.vu task management and time tracking.
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Streamable HTTP MCP server for Google Calendar and Sheets with OAuth login.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server for AI models to access and manipulate Apple Calendar data on macOS through a standardized interface.714MIT
- AlicenseDqualityDmaintenanceA Model Context Protocol server that allows users to interact with their CalDAV, CardDAV, and WebDAV services (calendars, contacts, and files) from Fastmail and Apple iCloud accounts.63MIT
- AlicenseNot gradedqualityCmaintenanceAn HTTP Model Context Protocol (MCP) server exposing iCloud Calendar (CalDAV) tools so MCP-aware clients can list calendars, read events, and create/update/delete events using an iCloud app-specific password.3MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Calendar via native EventKit API with proper recurring event support.13 npm10MIT