Apple Calendar MCP

Apple Calendar MCP는 macOS에서 AI 어시스턴트와 Apple Calendar를 안전하게 연결하기 위한 로컬 우선(local-first) MCP 서버입니다.

TypeScript MCP 서버, Swift EventKit 헬퍼, SQLite 로컬 상태, 그리고 네이티브 macOS 설정 앱으로 구성됩니다. 캘린더 데이터는 Mac에만 남습니다. 사용자가 표시할 캘린더를 선택하고, 쓰기 작업은 권한 모드, 확인 게이트, 중복 검사, 멱등성, 롤백 기록, 감사 로그, 변경 피드를 통해 보호받습니다.

주요 기능

• MCP 도구를 통해 Apple Calendar 캘린더, 일정, 가능 여부, 권한을 읽습니다.

• 기본적으로 미리 확인-확정(preview-confirm) 방식으로 일정을 생성, 수정, 재예약, 삭제합니다.

• 캘린더 허용 목록을 서버 측에서 강제하여 차단된 캘린더가 에이전트에 보이지 않게 합니다.

• 롤백 기록, 감사 기록, 컴팩트 스냅샷, 토큰을 절약하는 변경 피드를 추적합니다.

• Claude Desktop, Codex, Cursor, OpenClaw 및 일반 MCP 클라이언트용 클라이언트 구성을 생성합니다.

• 캘린더 권한, 허용 목록, 권한 모드, 구성 생성 및 검증을 위한 네이티브 macOS 설정 마법사를 제공합니다.

Related MCP server: nucleus-apple-mcp

아키텍처

flowchart TD
  A["MCP Client<br/>Claude, Codex, Cursor, OpenClaw"] --> B["TypeScript MCP Server"]
  B --> C["Calendar Service Layer"]
  C --> D["Swift EventKit Helper"]
  D --> E["Apple Calendar / EventKit"]
  C --> F["SQLite Local State"]
  F --> G["Config, Audit, Rollback,<br/>Snapshots, Change Feed,<br/>Idempotency"]
  H["Native macOS Setup App"] --> D
  H --> F

MCP 서버는 stdio로 통신합니다. 로그는 stdout이 아닌 stderr 또는 선택한 로컬 로그 파일에 기록되므로 MCP 프로토콜 트래픽은 오염되지 않습니다.

요구 사항

• Apple Calendar 및 EventKit에 접근할 수 있는 macOS.

• Node.js >=22.5.

• Xcode Command Line Tools 또는 Xcode를 통한 Swift 툴체인.

• Claude Desktop, Codex, Cursor, OpenClaw 또는 기타 stdio 호환 클라이언트와 같은 MCP 클라이언트.

소스에서 설치

git clone <repo-url>
cd apple-calendar-mcp
npm install
npm run build
npm run helper:bundle
npm run helper:setup

설정 앱은 다음 과정을 안내합니다.

1. 캘린더 권한 설명 및 요청.

2. 캘린더 허용 목록 선택.

3. 권한 모드 선택.

4. MCP 클라이언트 구성 생성.

5. 검증 확인 및 테스트 연결.

생성된 로컬 구성은 다음 위치에 저장됩니다.

~/Library/Application Support/AppleCalendarMCP/

MCP 클라이언트 설정

검증된 클라이언트 구성을 생성합니다.

npm run client-configs:generate

.generated/client-configs/에 생성된 파일을 클라이언트에 복사하거나 병합합니다.

• Claude Desktop: claude_desktop_config.json

• Codex: codex.config.toml을 ~/.codex/config.toml에 추가

• Cursor: cursor.mcp.json을 ~/.cursor/mcp.json 또는 프로젝트의 .cursor/mcp.json에 복사 또는 병합

• OpenClaw: openclaw.openclaw.json을 ~/.openclaw/openclaw.json에 병합

• 일반 MCP 클라이언트: generic-mcp-client.json 이용

복사 후 검증하세요.

npm run client-configs:validate
npm run client-configs:diagnose

생성된 구성은 절대 경로 Node 실행 파일과 절대 경로 MCP 서버 진입점 및 env 블록을 사용합니다. command와 args는 셸 문자열로 결합하지 않으므로 경로에 공백이 있어도 문제가 없습니다.

npx 실행 경로

배포 가능한 서버 패키지가 이 바이너리를 노출합니다.

npx apple-calendar-mcp

로컬 개발 및 릴리스 후보에는 다음을 권장합니다.

npm run start:mcp

npm에 게시하기 전에 내부 워크스페이스 패키지를 의존성 순서대로 게시하거나 npm run release:package가 생성한 릴리스 산출물을 사용하세요.

보안 모델

Apple Calendar MCP는 심층 방어를 기반으로 설계되었습니다.

• EventKit 접근 전에 macOS 캘린더 권한이 필수입니다.

• 캘린더 허용 목록은 에이전트가 볼 수 있는 캘린더를 제한합니다.

• 읽기 전용, 쓰기 전 확인, 신뢰할 수 있는 쓰기, 전체 쓰기 모드가 쓰기 리스크를 제어합니다.

• MVP 쓰기는 명시적 확인 또는 미리 확인-확정 플로우를 요구합니다.

• 파괴적이거나 모호한 작업은 추측하지 않고 의미 오류를 반환합니다.

• 반복 일정 쓰기에는 명시적 범위가 필요합니다.

• 캘린더 콘텐츠는 신뢰할 수 없는 입력으로 취급됩니다.

• 감사 기록, 롤백 기록, 멱등성 키, 변경 피드는 로컬에 기록됩니다.

전체 보안 모델은 docs/Security Specification.md를 확인하세요.

스크린샷

릴리스 스크린샷 자리 표시자:

• 설정 마법사 시작 및 캘린더 권한 단계.

• 캘린더 허용 목록 및 권한 모드 단계.

• 클라이언트 구성 및 검증 단계.

• 설정 및 진단화면.

공개 배포 전에 서명된 릴리스 스크린샷을 캡처하세요.

문제 해결

• 캘린더 접근이 거부됨: 시스템 설정 > 개인정보 보호 및 보안 > 캘린더를 열고 헬퍼 앱을 활성화하세요.

• 설정에서 MCP 서버가 빨간불: npm run build를 실행하고 packages/mcp-server/dist/index.js가 있는지 확인하세요.

• Cursor 또는 Codex가 접속하지 못하는 경우: npm run client-configs:generate로 구성을 다시 생성하고 복사한 구성이 절대 경로를 사용하는지 확인하세요.

• 클라이언트가 서버는 보는데 도구가 없음: 구성 변경 후 MCP 클라이언트를 다시 시작한 다음 npm run client-configs:diagnose를 실행하세요.

• stdout/stderr 분리 실패: MCP 서버 경로에서 stdout 로깅을 제거하세요. 로그는 stderr로 기록되어야 합니다.

• 대량 읽기 실패: 더 좁은 날짜 범위를 사용하세요. 읽기 서비스는 큰 범위를 내부적으로 집니다만, 아주 큰 EventKit 요청은 여전히 재시도가 필요할 수 있습니다.

개발

npm install
npm run build
npm test
npm run helper:bundle
npm run helper:setup

유용한 명령:

• npm run typecheck

• npm run client-configs:generate

• npm run client-configs:validate

• npm run release:verify

• npm run release:package

보안에 민감한 변경 전에 docs/Development Guide.md를 읽으세요.

저장소 구조

apps/macos-helper/        Swift EventKit bridge and native setup app
packages/mcp-server/      MCP stdio server and tool registration
packages/calendar-service/Business logic for reads, writes, rollback, snapshots
packages/sqlite-store/    Local SQLite persistence and migrations
packages/shared/          Shared schemas and typed contracts
scripts/                  Helper, config, diagnostics, and release scripts
tests/                    Phase-based safety and behavior tests
docs/                     Consolidated maintainer and release documentation

릴리스

재현 가능한 로컬 릴리스 산출물을 생성합니다.

npm run release:package

산출물과 체크섬은 다음 위치에 기록됩니다.

dist/release/

GitHub 릴리스 워크플로는 v* 태그 푸시 시 같은 패키지 스크립트를 실행합니다.

로드맵

• 서명 및 notarized된 macOS 배포 패키징.

• 패키지 네임스페이스 확인 후 공개 npm 게시 워크플로.

• 지원되는 MCP 클라이언트에 대한 추가 엔드투엔드 클라이언트 스모크 테스트.

• 스냅샷/변경 피드 페이지네이션 벤치마크 확장.

• 더 나은 인앱 스크린샷 캡처 및 공개 문서 자료.

기여

보안, 신뢰성, 사용자 신뢰, MCP 준수, 유지보수성을 편의보다 우선합니다. 변경 범위를 유지하고, 테스트 스위트 전체를 실행하고, 동작 변화 시 문서를 업데이트하세요. 권한 검사, 허용 목록, 확인 게이트, 롤백 기록, 감사 기록, 멱등성 검사 또는 의미 오류를 우회하지 마세요.

다음 문서부터 시작하세요.

• docs/Product Specification.md

• docs/Technical Specification.md

• docs/Security Specification.md

• docs/Development Guide.md

• docs/Installation Guide.md

• docs/Release Checklist.md