Apple Reminders MCP

Apple 리마인더(Reminders) 앱의 할일 목록을 Claude에서 직접 조회할 수 있는 MCP(Model Context Protocol) 서버입니다.

소개 및 제공 범위

이 MCP는 무엇인가요?

macOS의 Apple 리마인더 앱에 저장된 할일 데이터를 Claude 대화 안에서 자연어로 조회할 수 있게 해주는 로컬 MCP 서버입니다. "이번 주 마감 리마인더 뭐 있어?", "보험 관련 리마인더 찾아줘" 같은 질문을 Claude에게 직접 할 수 있습니다.

제공 기능

제공하지 않는 기능 (현재 버전)

• 리마인더 추가 / 수정 / 삭제 (읽기 전용)

• 반복 일정 정보 조회

• 하위 목록(그룹) 구분

• iCloud 동기화 상태 확인

데이터 흐름과 프라이버시

모든 데이터 처리는 로컬에서만 이루어집니다. 리마인더 데이터는 Claude 서버로 전송되어 대화 맥락에 포함될 수 있으므로, 민감한 내용이 포함된 리마인더 목록이 있다면 조회 범위를 특정 목록으로 한정해서 사용하는 것을 권장합니다.

지원 환경

• OS: macOS 12 Ventura 이상

• 클라이언트: Claude Desktop (로컬 MCP 서버 방식)

• 데이터 소스: 기기에 동기화된 Apple 리마인더 앱 데이터 (iCloud 포함)

Related MCP server: Apple Reminders MCP Server

동작 방식

Claude Desktop
    │
    │ (MCP stdio transport)
    ▼
index.js  ←── Node.js MCP 서버
    │
    │ (spawnSync)
    ▼
reminders_helper  ←── Swift 바이너리 (EventKit 사용)
    │
    │ (EventKit API)
    ▼
Apple Reminders 앱 데이터

AppleScript 대신 Swift + EventKit을 사용합니다. Node.js 자식 프로세스에서 AppleScript 반복문을 실행하면 ETIMEDOUT이 발생하는 macOS 제약이 있어, Swift 바이너리를 별도 컴파일해서 우회했습니다.

사전 요구사항

Xcode Command Line Tools 미설치 시:

xcode-select --install

설치

1. 저장소 복사

프로젝트를 원하는 위치에 복사합니다. 경로에 한글이나 특수문자가 있어도 괜찮습니다.

# 예시: 홈 디렉토리 아래에 배치
cp -r "apple-reminders-mcp" ~/

이 README에서는 설치 경로를 /Users/사용자명/apple-reminders-mcp로 가정합니다.

2. Node.js 의존성 설치

cd ~/apple-reminders-mcp
npm install

3. Swift 헬퍼 컴파일

cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper

컴파일이 성공하면 reminders_helper 실행 파일이 생성됩니다.

4. 동작 확인

# 리마인더 목록 확인 (macOS 권한 승인 팝업이 뜰 수 있음)
./reminders_helper lists

# 미완료 항목 조회
./reminders_helper get "__ALL__" "incomplete"

# 검색
./reminders_helper search "키워드"

첫 실행 시 macOS에서 리마인더 접근 권한 팝업이 표시됩니다. 허용을 클릭해야 합니다.

권한 설정 위치: 시스템 설정 → 개인정보 보호 및 보안 → 리마인더

Claude Desktop 연결 설정

설정 파일 위치

~/Library/Application Support/Claude/claude_desktop_config.json

설정 방법

파일을 열어 mcpServers 키를 추가합니다. 파일이 이미 있으면 기존 내용에 mcpServers 블록만 추가합니다.

설정 파일이 없는 경우 — 아래 내용으로 새로 생성:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/Users/사용자명/apple-reminders-mcp/index.js"]
    }
  }
}

설정 파일이 이미 있는 경우 — mcpServers 블록만 추가:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/Users/사용자명/apple-reminders-mcp/index.js"]
    }
  },
  "기존키": "기존값",
  ...
}

사용자명 부분을 실제 macOS 사용자 이름으로 바꿔야 합니다.
터미널에서 echo $HOME 으로 확인할 수 있습니다.

Node.js 경로 확인

시스템에 따라 Node.js가 다른 경로에 설치될 수 있습니다.

which node
# 예시 출력: /opt/homebrew/bin/node (Apple Silicon + Homebrew)
#           /usr/local/bin/node     (Intel Mac + Homebrew)
#           /usr/bin/node           (시스템 Node)

Homebrew로 설치된 경우 command에 절대 경로를 사용하는 것이 안전합니다:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/사용자명/apple-reminders-mcp/index.js"]
    }
  }
}

Claude Desktop 재시작

설정 파일 저장 후 Claude Desktop을 완전히 종료하고 다시 시작합니다.

Cmd+Q → Claude 재실행

재시작 후 새 대화에서 리마인더 목록 보여줘라고 입력하면 연결 확인이 됩니다.

제공 도구

list_reminder_lists

전체 리마인더 목록과 각 목록의 항목 수를 반환합니다.

입력: 없음

출력 예시:

📋 Todo — 전체 2개 (미완료 0개, 완료 2개)
📋 Reminders — 전체 1167개 (미완료 14개, 완료 1153개)
📋 Family — 전체 13개 (미완료 0개, 완료 13개)

get_reminders

특정 목록(또는 전체)에서 리마인더 항목을 가져옵니다.

입력:

사용 예:

• "Reminders" 목록의 미완료 항목 보여줘

• 전체 목록에서 완료된 항목 알려줘

• 모든 리마인더 목록 다 보여줘 (filter: all)

출력 예시:

⬜ 자동차보험 갱신
   목록: Reminders
   마감일: 2026. 11. 16. 오후 8:00

⬜ 공인인증서 갱신
   목록: Reminders
   마감일: 2026. 10. 25. 오후 1:00

search_reminders

모든 리마인더의 제목과 메모에서 키워드를 검색합니다.

입력:

사용 예:

• 보험 관련 리마인더 찾아줘

• 카드라는 키워드로 리마인더 검색해줘

트러블슈팅

MCP가 Claude에서 보이지 않을 때

1. claude_desktop_config.json 파일의 JSON 문법이 올바른지 확인합니다.

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

2. index.js 경로가 정확한지 확인합니다.

   ls -la "/Users/사용자명/apple-reminders-mcp/index.js"

3. Claude Desktop을 완전히 종료 후 재시작합니다 (Cmd+Q).

"reminders_helper를 찾을 수 없음" 오류

Swift 바이너리가 컴파일되지 않은 상태입니다.

cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper

"권한 없음" 오류

시스템 설정에서 리마인더 접근 권한을 확인합니다.

시스템 설정 → 개인정보 보호 및 보안 → 리마인더

reminders_helper 또는 터미널 앱이 목록에 없으면, 터미널에서 직접 실행해 권한 팝업을 승인합니다:

~/apple-reminders-mcp/reminders_helper lists

Node.js를 찾을 수 없음 오류

claude_desktop_config.json의 command에 Node.js 절대 경로를 지정합니다:

which node  # 경로 확인

Mac 재설치 후 재세팅 체크리스트

새 Mac 또는 클린 설치 후 복원 순서입니다.

• Xcode Command Line Tools 설치: xcode-select --install

• Node.js 설치 (Homebrew 권장): brew install node

• 프로젝트 파일 복사 (Time Machine 또는 수동 복사)

• npm install 실행

• swiftc reminders_helper.swift -o reminders_helper 컴파일

• ./reminders_helper lists 실행해서 리마인더 권한 승인

• claude_desktop_config.json에 mcpServers 설정 추가

• Claude Desktop 재시작 후 연결 확인

Swift 바이너리(reminders_helper)는 macOS 버전/아키텍처마다 다르므로 항상 새로 컴파일해야 합니다. 백업할 때는 .swift 소스 파일만 있으면 충분합니다.

파일 구조

apple-reminders-mcp/
├── index.js                  Node.js MCP 서버 (stdio transport)
├── reminders_helper.swift    Swift 헬퍼 소스 (EventKit)
├── reminders_helper          컴파일된 바이너리 ← 재설치 시 재컴파일 필요
├── package.json
├── package-lock.json
├── node_modules/
└── README.md

백업 시 reminders_helper 바이너리는 제외해도 되며, node_modules도 npm install로 재생성할 수 있습니다. 필수 파일은 index.js, reminders_helper.swift, package.json입니다.