# 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`입니다.