# apple-reminders-mcp

An MCP server that connects Claude Desktop to Apple Reminders on macOS via AppleScript.

## Prerequisites

- macOS
- [Node.js](https://nodejs.org) 18+
- [Claude Desktop](https://claude.ai/download)

## Installation

**1. Add to Claude Desktop config**

Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:

```json
{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "@kamk95/apple-reminders-mcp"]
    }
  }
}
```

**2. Restart Claude Desktop**

The first time a reminder tool is used, macOS will prompt you to grant Reminders access — click Allow.

---

### Manual install (alternative)

If you prefer to run from source:

```bash
git clone https://github.com/kamrenkennedy/apple-reminders-mcp.git
cd apple-reminders-mcp
npm install
```

Then use this config instead:

```json
{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/apple-reminders-mcp/index.js"]
    }
  }
}
```

---

## Tools

### `list_reminders`
List reminders across all lists or a specific one.

| Parameter | Type | Description |
|---|---|---|
| `list_name` | string | Filter to a specific list (optional) |
| `include_completed` | boolean | Include completed reminders (default: false) |

### `create_reminder`
Create a new reminder.

| Parameter | Type | Description |
|---|---|---|
| `name` | string | **Required.** Title of the reminder |
| `list_name` | string | Destination list (default: Reminders) — created if it doesn't exist |
| `due_date` | string | Due date in `YYYY-MM-DD` format |
| `due_time` | string | Due time in `HH:MM` 24-hour format — requires `due_date` |
| `priority` | string | `none` / `low` / `medium` / `high` / `urgent` |
| `notes` | string | Body/notes text |
| `tags` | string[] | Tags to attach |

### `complete_reminder`
Mark a reminder as completed.

| Parameter | Type | Description |
|---|---|---|
| `name` | string | **Required.** Exact name of the reminder |
| `list_name` | string | Narrow search to this list (optional) |

### `delete_reminder`
Permanently delete a reminder.

| Parameter | Type | Description |
|---|---|---|
| `name` | string | **Required.** Exact name of the reminder |
| `list_name` | string | Narrow search to this list (optional) |

### `update_reminder`
Update any fields on an existing reminder. Only provided fields are changed.
If you update `notes` or `tags` individually, the other is preserved automatically.

| Parameter | Type | Description |
|---|---|---|
| `name` | string | **Required.** Current name of the reminder |
| `list_name` | string | Current list to narrow the search |
| `new_name` | string | Rename the reminder |
| `new_list_name` | string | Move reminder to this list |
| `due_date` | string | New due date in `YYYY-MM-DD` format |
| `due_time` | string | New due time in `HH:MM` 24-hour format |
| `clear_due_date` | boolean | Remove the due date entirely |
| `priority` | string | `none` / `low` / `medium` / `high` / `urgent` |
| `notes` | string | Replace notes text |
| `tags` | string[] | Replace tags |

---

## Notes

- **Tags** are stored inside the reminder's notes field as `[tags: tag1, tag2]` since the native Reminders tags API is not accessible via AppleScript. They round-trip correctly through all tools.
- Reminders are matched by exact name. If you have duplicates across lists, pass `list_name` to disambiguate.