yandex-calendar-mcp

CalDAV를 통해 Yandex Calendar에 AI 어시스턴트가 접근할 수 있게 해주는 MCP 서버입니다. 일정을 읽고, 이벤트를 생성·이동·삭제할 수 있습니다.

Русская версия

언어에 관한 참고: 도구 설명과 응답이 러시아어입니다. 이 서버가 러시아어를 사용하는 어시스턴트를 위해 작성되었기 때문입니다. 코드, 설정, 이 문서는 영어입니다. 그 외에는 언어와 관계없이 모두 동작합니다.

기능

읽기

• 임의 기간의 이벤트: 기본값은 오늘, 또는 최대 92일 범위를 명시적으로 지정할 수 있습니다.

• 모든 캘린더를 한 번에 가져오되 이벤트가 어떤 캘린더에서 왔는지 표시 — 또는 이름으로 선택한 단일 캘린더만 조회.

• 반복 이벤트를 구체적인 날짜로 확장합니다. 확장에 실패하면 해당 이벤트는 정확한 결과로 제시되지 않고 경고와 함께 반환됩니다.

• 참석자 목록과 각자의 응답 상태(수락, 거절, 보류, 아직 응답 없음)가 함께 표시됩니다.

• 종일 이벤트는 종일 이벤트로 인식되며, 자정 약속으로 표시되지 않습니다.

• 모든 응답에서 사용된 시간대와 UTC 오프셋을 설명합니다.

쓰기

• 이벤트 생성: 제목, 시작, 종료 또는 기간, 장소, 설명 또는 시간 단위 또는 여러 날에 걸친 종일 일정으로 생성 가능.

• 반복 이벤트 생성 — 매일, 매주, 매월 또는 매년 — 반복 횟수나 종료 날짜로 제한.

• 이벤트 업데이트: 이동, 이름 변경, 장소 또는 설명 변경. 전달한 필드만 영향을 받고, 이동된 이벤트는 다른 지정이 없으면 원래 기간을 유지합니다.

• 반복 일정의 **단일 첫 발생(zero occurrence)**을 수정/삭제하거나 시리즈 전체를 수정/삭제할 수 있습니다. 변경된 날짜는 RECURRENCE-ID 오버라이드로, 삭제된 날짜는 EXDATE로 저장됩니다. 즉, Yandex 앱과 모든 클라이언트에서 표준적인 모습을 유지합니다.

• 참석자를 초대할 수 있습니다. 이벤트 생성 시 참석자를 추가할 수 있으며 이후에도 추가/제거가 가능합니다. 초대장과 취소 알림은 Yandex가 직접 메일로 발송합니다.

• 이벤트 삭제 — 아래 설명할 안전장치와 함께.

시간대, 신중하게 처리

• 모든 타임스탬프는 zoneinfo를 사용하여 설정된 시간대로 변환합니다. 시간 문자열은 문자 단위로 슬라이스하지 않습니다.

• 생성된 이벤트에는 명시적인 DTSTART;TZID=…와 전체 VTIMEZONE 블록이 포함되므로, 어떤 캘린더 클라이언트든 동일하게 해석합니다.

• 서버가 실행되는 장비는 토대적으로 UTC를 사용합니다. 그 값이 응답에 그대로 노출되지는 않지만, 실제 사용된 시간대를 모든 응답에 명시하기 때문에 잘못 사용해도 눈치채기 어렵지 않으므로 침묵하기 않고 오류가 드러납니다.

어시스턴트가 주도하기 위해 설계됨

• 응답에는 이벤트 uid가 포함된 일반 텍스트로 오류, 편집/삭제가 조회 직후 바로 이어질 수 있습니다.

• create_event는 반드시 문시적인 캘린더를 요구합니다. 사람들은 목적별로 여러 캘린더를 만들기도 하며, 잘못된 캘린더에 조용히 들어가는 것은 곧 이벤트를 잃는 셈입니다. 따라서 어시스턴트는 추측하지 말고 반드시 질문해야 합니다.

• 오류는 스택 트레이스가 아니라, 다음에 무엇을 해야 하는지를 설명하는 문장으로 반환됩니다.

Related MCP server: MCP Personal Calendar

요구 사항(Requirements)

• Python 3.10 or 3.13 tested.

• 이벤트 변경: Yandex 앱 전용 비밀번호가 필요합니다. (계정 비밀번호와 다름): https://id.yandex.ru/security/app-passwords → 유형 "Календарь (CalDAV)"

pip install -r requirements.txt

tzdata가 일부러 요구 사항에 포함되어 있습니다. 슬림한 Linux 이미지들에는 시간대 데이터베이스가 없는 경우가 많기 때문에, ZoneInfo("Europe/Moscow")가 오류를 낼 수 있습니다.

설정

모든 설정은 환경 변수로 관리합니다.

서버는 stdio를 통해 MCP를 지원합니다. 예시 클라이언트 구성은 examples/에서 볼 수 있습니다.

도구

삭제는 되돌릴 수 없습니다 — 보호 장치

1. 제목 확인. delete_event는 uid와 이벤트 제목을 함께 받습니다. 두 값을 비교하며, 일치하지 않을 경우 아무것도 삭제하지 않고 두 제목과 캘린더 이름을 반환합니다. 오래된 uid를 사용해 잘못된 이벤트를 지우는 실수를 예방하기 위한 조정입니다.

2. 휴지통. 모든 삭제 및 변경 작업 전에 원본 이벤트 전체를 YANDEX_TRASH_DIR에 타임스탬프가 붙은 .ics 파일로 만듭니다. 사본을 쓸 수 없다면 작업 자체를 실행하지 않습니다. 복구는 해당 파일을 다시 가져오는 단순한 방법입니다.

3. 반복 시리즈. 반복 이벤트에서 무엇이라도 수정·삭제하려면 적용 대상을 지정해야 합니다: occurrence(특정 하루) 또는 apply_to_series(전체 시리즈). 아무것도 지정하지 않으면 도구가 아예 거부하며 그 선택지를 설명합니다. 이 방식이 "화요일 일정 취소"가 1년간 회의를 전부 삭제하는 사고를 막습니다.

참석자 초대는 실제 이메일이 발송합니다

Yandex은 calendar-auto-schedule을 지원하므로, 참석자를 추가하면 서버가 초대 메일을 보내고, 참석자를 제거하면 취소 메일을 보냅니다. 이메일을 되돌릴 수 없습니다. 이 기능은 서버가 명시한 것만이 아니라 실제로 확인되었습니다. create_event로 추가한 참석자에게 초대 이메일이 실제로 도착했습니다.

이로부터: 예외는 없습니다.

• 주소는 문자 그대로 검증됩니다. 주소를 이름에서 추측하지 않습니다. 만약 그렇게 했다면, 일부 실수로 메일을 보내려는 경우에 else 끝나기지면 이 서버는 얼굴을 보지 않고 주소를 단지 교환하게 됩니다.

• update_event는 목록을 대체하지 않고 참석자를 추가·제거하기 때문에, 이미 다른 사람이 응답한 결과를 유지합니다.

• 모든 응답마다 누가 참석하고 어떻게 응답했는지 정확히 표시하므로, 잘못된 주소를 확인할 수 있습니다.

이 서버를 제어하는 어시스턴트는 호출 전에 사용자와 참석자 주소 목록을 확인해야 합니다. 초대 메일은 취소할 수 없는 조치입니다.

테스트

python tests/write_cycle.py "Calendar name"

실제 프로토콜와 실제 캘린더를 이용해 테스트한 후 자체 정리한다.

1회 이벤트: 생성 → 잘못된 제목으로 삭제 시도(거부되어야 함) → 이동 및 이름 변경 → 목록에 나타나는지 확인 → 삭제 → 삭제 확인

반복 3회: 특정 하루 편집, 특정 하루 삭제, 전체 시리즈 삭제를 확인. 각 단계에서 정확히 하나의 날짜만이 변경되었는지 확인하고, 불일치 시 남아 있는 이벤트의 uid를 알려주고 조용히 덮어두지 않는다.

참석자 라운드는 실제 이메일을 발송하기 때문에 명시적으로 주소가 전달된 경우에만 수행됩니다.

python tests/write_cycle.py "Calendar name" someone@example.com

tests/probe.jsonl은 핸드셰이크와 읽기 경로를 확인하기 위한 일련의 원시 프로토콜 메시지입니다.

python src/server.py < tests/probe.jsonl

알려진 제한 사항

• 종일 이벤트는 생성할 수 있지만, 그 시간/일자는 이동할 수 없습니다.

• 순환 규칙은 일반적인 형태(매일/매주/매월/매년)과 제한(횟수 또는 종료일)만 생성할 수 있습니다. 더 복잡한 규칙 — "둘째 주 화요일", 특정 요일 집합 등 — 읽기/확장은 가능하지만 도구로 생성할 수 없습니다.

• 미리 알림과 알림(reminders/alarms)은 처리하지 않습니다.

• 참석자는 항상 필수 참석자로 초대됩니다. optional 참석자나 참석자 역할은 지원하지 않습니다.

• Yandex Calendar에서만 검증했습니다. 다른 CalDAV 서버의 작동 가능할 수 있지만 테스트는 아닙니다.

라이선스

MIT — LICENSE(를) 참조하세요.