Content
# Apple Reminders MCP
Apple Reminders app's task list can be directly queried in Claude with this MCP (Model Context Protocol) server.
## Introduction and Scope
### What is this MCP?
This is a local MCP server that allows you to query task data stored in the Apple Reminders app on macOS within Claude conversations in natural language. You can ask Claude questions like "What reminders do I have due this week?" or "Find reminders related to insurance".
### Features
| Feature | Description |
|---|---|
| List Retrieval | Retrieve all reminder lists and the number of incomplete/complete items for each list |
| Item Retrieval | Filter and retrieve specific reminders from a list or all lists |
| Keyword Search | Search for keywords in title and memo contents |
| Metadata Display | Display due date, memo, priority, and completion date |
### Features Not Provided (Current Version)
- Add / Edit / Delete reminders (read-only)
- Recurring schedule information retrieval
- Sub-list (group) distinction
- iCloud synchronization status check
### Data Flow and Privacy
All data processing occurs **locally only**. Reminders data can be transmitted to Claude servers for conversational context, so it's recommended to limit the query range to specific lists if sensitive content is included.
### Supported Environment
- **OS**: macOS 12 Ventura or later
- **Client**: Claude Desktop (local MCP server method)
- **Data Source**: Apple Reminders app data synchronized to the device (including iCloud)
## Operation Method
```
Claude Desktop
│
│ (MCP stdio transport)
▼
index.js ←── Node.js MCP server
│
│ (spawnSync)
▼
reminders_helper ←── Swift binary (using EventKit)
│
│ (EventKit API)
▼
Apple Reminders app data
```
Using Swift + EventKit instead of AppleScript. Node.js child process execution of AppleScript loop causes ETIMEDOUT on macOS, so a separate Swift binary compilation was implemented.
## Prerequisites
| Item | Minimum Version | Verification Command |
|---|---|---|
| macOS | 12 Ventura or later | `sw_vers` |
| Node.js | v18 or later | `node --version` |
| Xcode Command Line Tools | Swift 5.9 or later | `swiftc --version` |
| Claude Desktop | Latest version | — |
If Xcode Command Line Tools are not installed:
```bash
xcode-select --install
```
## Installation
### 1. Copy Repository
Copy the project to a desired location.
```bash
# Example: place under home directory
cp -r "apple-reminders-mcp" ~/
```
This README assumes the installation path is `/Users/username/apple-reminders-mcp`.
### 2. Install Node.js Dependencies
```bash
cd ~/apple-reminders-mcp
npm install
```
### 3. Compile Swift Helper
```bash
cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper
```
After successful compilation, the `reminders_helper` executable file is generated.
### 4. Verify Operation
```bash
# Verify reminder lists (macOS permission pop-up may appear)
./reminders_helper lists
# Retrieve incomplete items
./reminders_helper get "__ALL__" "incomplete"
# Search
./reminders_helper search "keyword"
```
On the first run, a macOS **Reminders access permission** pop-up will appear. Click **Allow**.
> Permission setting location: System Settings → Privacy & Security → Reminders
## Claude Desktop Connection Settings
### Configuration File Location
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
### Configuration Method
Open the file and add the `mcpServers` key. If the file already exists, add only the `mcpServers` block.
**If the configuration file does not exist** — create a new file with the following content:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "node",
"args": ["/Users/username/apple-reminders-mcp/index.js"]
}
}
}
```
**If the configuration file already exists** — add only the `mcpServers` block:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "node",
"args": ["/Users/username/apple-reminders-mcp/index.js"]
}
},
"existing_key": "existing_value",
...
}
```
> Replace `username` with the actual macOS user name.
> Can be verified with `echo $HOME` in the terminal.
### Node.js Path Verification
Node.js may be installed in a different path depending on the system.
```bash
which node
# Example output: /opt/homebrew/bin/node (Apple Silicon + Homebrew)
# /usr/local/bin/node (Intel Mac + Homebrew)
# /usr/bin/node (system Node)
```
For Homebrew installations, it's safer to use an absolute path in the `command`:
```json
{
"mcpServers": {
"apple-reminders": {
"command": "/opt/homebrew/bin/node",
"args": ["/Users/username/apple-reminders-mcp/index.js"]
}
}
}
```
### Claude Desktop Restart
Save the configuration file and completely restart Claude Desktop.
```
Cmd+Q → Restart Claude
```
After restarting, input `Show reminder list` in a new conversation to verify the connection.
## Provided Tools
### `list_reminder_lists`
Returns all reminder lists and the number of items for each list.
**Input:** None
**Output Example:**
```
📋 Todo — Total 2 (0 incomplete, 2 complete)
📋 Reminders — Total 1167 (14 incomplete, 1153 complete)
📋 Family — Total 13 (0 incomplete, 13 complete)
```
## `get_reminders`
Retrieves reminder items from a specific list (or all lists).
**Input:**
| Parameter | Type | Default Value | Description |
|---|---|---|---|
| `list_name` | string | (all) | List name. Omitting it retrieves all lists |
| `filter` | string | `incomplete` | `incomplete` / `completed` / `all` |
**Usage Examples:**
- `"Reminders" list incomplete items`
- `Complete items in all lists`
- `Show all reminder lists` (filter: all)
**Output Example:**
```
⬜ Car insurance renewal
List: Reminders
Due Date: 2026. 11. 16. 8:00 PM
⬜ Public certificate renewal
List: Reminders
Due Date: 2026. 10. 25. 1:00 PM
```
## `search_reminders`
Searches for keywords in all reminder titles and memos.
**Input:**
| Parameter | Type | Required | Description |
|---|---|---|---|
| `keyword` | string | Required | Search keyword (case-insensitive) |
**Usage Examples:**
- `Find insurance-related reminders`
- `Search reminders with the keyword "card"`
## Troubleshooting
### MCP Not Visible in Claude
1. Verify the JSON syntax of the `claude_desktop_config.json` file.
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool
```
2. Verify the `index.js` path.
```bash
ls -la "/Users/username/apple-reminders-mcp/index.js"
```
3. Completely restart Claude Desktop (`Cmd+Q`).
### "reminders_helper not found" Error
The Swift binary was not compiled.
```bash
cd ~/apple-reminders-mcp
swiftc reminders_helper.swift -o reminders_helper
```
### "No Permission" Error
Verify Reminders access permission in System Settings.
```
System Settings → Privacy & Security → Reminders
```
If `reminders_helper` or Terminal app is not listed, execute it directly to approve the permission pop-up:
```bash
~/apple-reminders-mcp/reminders_helper lists
```
### Node.js Not Found Error
Specify the absolute path of Node.js in `claude_desktop_config.json`:
```bash
which node # Verify path
```
## Mac Reinstallation Checklist
Post-reinstallation or clean installation restoration steps.
- [ ] Install Xcode Command Line Tools: `xcode-select --install`
- [ ] Install Node.js (Homebrew recommended): `brew install node`
- [ ] Copy project files (Time Machine or manual copy)
- [ ] Execute `npm install`
- [ ] Compile `swiftc reminders_helper.swift -o reminders_helper`
- [ ] Execute `./reminders_helper lists` for Reminders permission approval
- [ ] Add mcpServers configuration to `claude_desktop_config.json`
- [ ] Restart Claude Desktop and verify connection
> Swift binary (`reminders_helper`) differs by macOS version/architecture, so **compile it every time**. Only the `.swift` source file needs to be backed up.
## File Structure
```
apple-reminders-mcp/
├── index.js Node.js MCP server (stdio transport)
├── reminders_helper.swift Swift helper source (EventKit)
├── reminders_helper Compiled binary ← Recompile required after reinstall
├── package.json
├── package-lock.json
├── node_modules/
└── README.md
```
The `reminders_helper` binary can be excluded from backups, and `node_modules` can be regenerated with `npm install`. Essential files are `index.js`, `reminders_helper.swift`, and `package.json`.
