mcp-ical-swift

macOS Sequoia의 TCC 제한을 우회하기 위해 컴파일된 Swift 바이너리를 사용하는 Apple Calendar용 로컬 MCP 서버입니다.

이 프로젝트의 존재 이유

macOS Sequoia(26.x)에서 헤드리스 프로세스는 표준 TCC(Transparency, Consent, and Control) 메커니즘을 통해 캘린더 액세스 권한을 얻을 수 없습니다:

• Python의 EventKit(예: PyObjC)은 kTCCServiceCalendar가 필요한데, 이는 헤드리스 프로세스가 트리거할 수 없는 시스템 대화 상자를 통해서만 부여될 수 있습니다. Sequoia의 시스템 설정 > 개인정보 보호 및 보안 > 캘린더에는 + 버튼이 없습니다.

• osascript를 통한 AppleScript는 kTCCServiceAppleEvents(자동화 권한)가 필요한데, 이는 호출하는 바이너리(일반적으로 node 또는 bun)에 귀속됩니다. TCC 데이터베이스를 직접 수정하는 것은 TCC 데몬의 무결성 검사에 의해 조용히 무시됩니다.

• icalBuddy 및 기타 Homebrew 도구는 내부적으로 EventKit을 사용하므로 동일한 벽에 부딪힙니다.

컴파일된 Swift 바이너리(swiftc)가 작동하는 이유는 시스템 Swift 툴체인으로부터 캘린더 TCC 권한을 상속받는 Apple 서명 Mach-O 실행 파일을 생성하기 때문입니다. Node/Bun이 execFileSync를 통해 이 바이너리를 실행하면, EventKit은 authorizationStatus = .fullAccess를 보고하고 캘린더 데이터를 반환합니다.

기능

• 모든 캘린더 나열

• 날짜 범위 내 이벤트 나열

• 키워드로 이벤트 검색

• 새 이벤트 생성 (캘린더, 위치, 메모, 종일 지원)

• 기존 이벤트 업데이트

• UID로 전체 이벤트 세부 정보 가져오기

• 이벤트 삭제

• stdio를 통해 완전히 로컬에서 실행 -- 네트워크, API 키, 클라우드 없음

사전 요구 사항

• macOS Sequoia(26.x) 이상

• Bun 1.1 이상

• swiftc를 위한 Xcode Command Line Tools (xcode-select --install)

• Apple Calendar의 캘린더 데이터 (iCloud, Exchange 또는 로컬 캘린더)

설치

git clone https://github.com/Sealjay/mcp-ical-swift.git
cd mcp-ical-swift
bun install
bun run build

build 스크립트는 src/calendar-reader.swift를 bin/calendar-reader로 컴파일합니다.

MCP 클라이언트 구성

Claude Code

claude mcp add --transport stdio ical --scope user -- bun run /absolute/path/to/mcp-ical-swift/src/index.ts

OpenClaw

{
  "mcp": {
    "servers": {
      "ical": {
        "command": "bun",
        "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "ical": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-ical-swift/src/index.ts"]
    }
  }
}

도구

작동 원리

MCP Client (Claude, OpenClaw, etc.)
  --> stdio --> Bun MCP server (src/index.ts)
    --> execFileSync --> compiled Swift binary (bin/calendar-reader)
      --> EventKit framework --> Apple Calendar data

Swift 바이너리는 한 번 컴파일(bun run build)되며 각 도구 호출 시 동기적으로 호출됩니다. 이 바이너리는 JSON을 stdout으로 출력하고, Bun MCP 서버는 이를 MCP 도구 결과로 래핑합니다. 서버는 주입 위험을 피하기 위해 execFileSync(쉘 실행이 아님)를 사용합니다.

핵심 통찰: swiftc로 컴파일된 바이너리는 Apple 서명이 되어 있으며 시스템 툴체인으로부터 캘린더 TCC 권한을 상속받습니다. 이는 Node, Bun, Python 및 AppleScript가 헤드리스 컨텍스트에서 캘린더에 액세스하는 것을 차단하는 TCC 제한을 우회합니다.

개인정보 보호 및 보안

• 이 서버는 기본적으로 시스템의 모든 캘린더(iCloud, Exchange, 로컬, 공유, 구독)에 액세스합니다. list_events 및 search_events에서 선택적 calendar 매개변수를 사용하여 요청별로 캘린더 이름을 필터링할 수 있습니다.

• 이벤트 메모는 응답에 포함되어 반환되며 민감한 데이터(회의 PIN, 비밀번호, 개인 정보)가 포함될 수 있습니다. MCP 클라이언트 액세스 권한을 부여할 때 이 점을 고려하십시오.

• 쓰기 작업(create_event, update_event, delete_event)은 확인 단계 없이 사용할 수 있습니다. MCP 클라이언트(또는 그 안의 프롬프트 주입)가 캘린더 데이터를 수정할 수 있습니다.

• 모든 통신은 stdio를 통해 로컬에서 이루어지며 외부 서비스로 데이터가 전송되지 않습니다.

• 취약점을 보고하려면 SECURITY.md를 참조하십시오.

제한 사항

• macOS 전용 (EventKit 및 Swift 툴체인 필요)

• Bun 런타임 필요

• Swift 바이너리는 한 번 컴파일되어 도구 호출당 동기적으로 호출되므로 매우 높은 처리량의 사용에는 적합하지 않음

• 반복 이벤트 수정은 단일 인스턴스에만 적용됨 (.thisEvent 범위)

• 캘린더 액세스는 macOS TCC가 컴파일된 바이너리에 권한을 부여하는지에 따라 달라짐

문제 해결

"Calendar access is not granted" (캘린더 액세스 권한이 부여되지 않음)

컴파일된 바이너리는 캘린더 TCC 권한이 있는 컨텍스트에서 최소 한 번은 실행되어야 합니다. 빌드 및 테스트를 실행하세요:

bun run build
bin/calendar-reader list-events $(date +%Y-%m-%d)

이 명령이 이벤트를 반환하면 바이너리에 캘린더 액세스 권한이 있는 것입니다. 그렇지 않다면 Terminal.app(일반적으로 캘린더 TCC 권한이 부여됨)에서 실행해 보십시오.

이벤트가 비어 있음

Apple Calendar에 캘린더가 구성되어 있는지 확인하십시오. 다음을 실행하세요:

bin/calendar-reader list-calendars

컴파일 실패

Xcode Command Line Tools가 설치되어 있는지 확인하십시오:

xcode-select --install

라이선스

MIT