内容
# 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 포함)
---
## 동작 방식
```
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 바이너리를 별도 컴파일해서 우회했습니다.
---
## 사전 요구사항
| 항목 | 최소 버전 | 확인 명령 |
|---|---|---|
| macOS | 12 Ventura 이상 | `sw_vers` |
| Node.js | v18 이상 | `node --version` |
| Xcode Command Line Tools | Swift 5.9 이상 | `swiftc --version` |
| Claude Desktop | 최신 버전 | — |
Xcode Command Line Tools 미설치 시:
```bash
xcode-select --install
```
---
## 설치
### 1. 저장소 복사
프로젝트를 원하는 위치에 복사합니다. 경로에 한글이나 특수문자가 있어도 괜찮습니다.
```bash
# 예시: 홈 디렉토리 아래에 배치
cp -r "apple-reminders-mcp" ~/
```
이 README에서는 설치 경로를 `/Users/사용자명/apple-reminders-mcp`로 가정합니다.
### 2. Node.js 의존성 설치
```bash
cd ~/apple-reminders-mcp
npm install
```
### 3. Swift 헬퍼 컴파일
```bash
cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper
```
컴파일이 성공하면 `reminders_helper` 실행 파일이 생성됩니다.
### 4. 동작 확인
```bash
# 리마인더 목록 확인 (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` 블록만 추가합니다.
**설정 파일이 없는 경우** — 아래 내용으로 새로 생성:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "node",
"args": ["/Users/사용자명/apple-reminders-mcp/index.js"]
}
}
}
```
**설정 파일이 이미 있는 경우** — `mcpServers` 블록만 추가:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "node",
"args": ["/Users/사용자명/apple-reminders-mcp/index.js"]
}
},
"기존키": "기존값",
...
}
```
> `사용자명` 부분을 실제 macOS 사용자 이름으로 바꿔야 합니다.
> 터미널에서 `echo $HOME` 으로 확인할 수 있습니다.
### Node.js 경로 확인
시스템에 따라 Node.js가 다른 경로에 설치될 수 있습니다.
```bash
which node
# 예시 출력: /opt/homebrew/bin/node (Apple Silicon + Homebrew)
# /usr/local/bin/node (Intel Mac + Homebrew)
# /usr/bin/node (시스템 Node)
```
Homebrew로 설치된 경우 `command`에 절대 경로를 사용하는 것이 안전합니다:
```json
{
"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`
특정 목록(또는 전체)에서 리마인더 항목을 가져옵니다.
**입력:**
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| `list_name` | string | (전체) | 목록 이름. 생략하면 전체 목록 조회 |
| `filter` | string | `incomplete` | `incomplete` / `completed` / `all` |
**사용 예:**
- `"Reminders" 목록의 미완료 항목 보여줘`
- `전체 목록에서 완료된 항목 알려줘`
- `모든 리마인더 목록 다 보여줘` (filter: all)
**출력 예시:**
```
⬜ 자동차보험 갱신
목록: Reminders
마감일: 2026. 11. 16. 오후 8:00
⬜ 공인인증서 갱신
목록: Reminders
마감일: 2026. 10. 25. 오후 1:00
```
---
### `search_reminders`
모든 리마인더의 제목과 메모에서 키워드를 검색합니다.
**입력:**
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| `keyword` | string | 필수 | 검색할 키워드 (대소문자 무시) |
**사용 예:**
- `보험 관련 리마인더 찾아줘`
- `카드라는 키워드로 리마인더 검색해줘`
---
## 트러블슈팅
### MCP가 Claude에서 보이지 않을 때
1. `claude_desktop_config.json` 파일의 JSON 문법이 올바른지 확인합니다.
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
```
2. `index.js` 경로가 정확한지 확인합니다.
```bash
ls -la "/Users/사용자명/apple-reminders-mcp/index.js"
```
3. Claude Desktop을 완전히 종료 후 재시작합니다 (`Cmd+Q`).
### "reminders_helper를 찾을 수 없음" 오류
Swift 바이너리가 컴파일되지 않은 상태입니다.
```bash
cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper
```
### "권한 없음" 오류
시스템 설정에서 리마인더 접근 권한을 확인합니다.
```
시스템 설정 → 개인정보 보호 및 보안 → 리마인더
```
`reminders_helper` 또는 터미널 앱이 목록에 없으면, 터미널에서 직접 실행해 권한 팝업을 승인합니다:
```bash
~/apple-reminders-mcp/reminders_helper lists
```
### Node.js를 찾을 수 없음 오류
`claude_desktop_config.json`의 `command`에 Node.js 절대 경로를 지정합니다:
```bash
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`입니다.
