apple-reminders-for-claude

# Apple Reminders for Claude

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![macOS 11+](https://img.shields.io/badge/macOS-11%2B-informational)](https://support.apple.com/macos)
[![Notarized](https://img.shields.io/badge/Apple-Notarized-success)](https://support.apple.com/en-us/HT202491)
[![MCPB manifest](https://img.shields.io/badge/MCPB-0.3-000)](https://github.com/anthropics/mcpb)

Fast, native Apple Reminders access for Claude — works in **Claude Desktop**, **Claude Cowork**, and **Claude Code** (CLI). One signed Swift/EventKit binary, three distribution packages.

Reminder IDs are stable across sessions. A full CRUD round-trip takes under a second on a database with 300+ reminders. Umlauts, accents, CJK characters and emoji pass through unchanged.

**Published by [high5 ventures GmbH](https://h5ventures.de)** — signed with `Developer ID Application: high5 ventures GmbH` and notarized by Apple.

---

## Quick start

You need a Mac (Apple Silicon or Intel) running macOS 11 or later, and Claude Desktop.

1. Download **`apple-reminders.mcpb`** from the [latest release](https://github.com/high5-ventures/apple-reminders-for-claude/releases/latest).
2. Double-click it. Claude Desktop opens an install dialog — click **Install**.
3. Ask Claude something like **"What's on my reminders for today?"**

macOS asks for Reminders access on that first question. Allow it, and Claude can read and change your reminders.

No configuration is needed: the bundle contains the server and the signed binary, and Claude Desktop sets the paths on install.

Updating is the same three steps with the newer `.mcpb`.

> Not using Claude Desktop? See [Installation](#installation) for Claude Code and other MCP clients.

---

## Contents

- [Description](#description)
- [Features](#features)
- [Usage examples](#usage-examples)
- [Installation](#installation)
- [Configuration](#configuration)
- [MCP tools](#mcp-tools)
- [Privacy policy](#privacy-policy)
- [Troubleshooting](#troubleshooting)
- [Support](#support)
- [Architecture](#architecture)
- [License](#license)

---

## Description

Apple Reminders for Claude gives Claude full CRUD access to your macOS Reminders app. It wraps Apple's native **EventKit** framework in a signed Swift binary that returns stable UUIDs and structured JSON, and ships three ways:

| Target | Artifact | Where to get it |
|---|---|---|
| **Claude Desktop / Cowork** | `.mcpb` bundle | [Releases](https://github.com/high5-ventures/apple-reminders-for-claude/releases) |
| **Claude Code** (CLI) | Plugin with skill | `/plugin marketplace add` against this repository |
| **Any MCP client** | npm package | `npm install -g @high5ventures/apple-reminders-mcp` |

All three ship the same binary and the same 13 tools, so behaviour does not differ between them.

## Features

- **13 MCP tools** covering the full reminder lifecycle: list lists, list reminders (open/completed/all), full-text search, today/overdue/scheduled smart queries, CRUD on individual reminders.
- **Native EventKit** — not AppleScript, not reverse-engineered SQLite scraping.
- **Stable UUIDs** — reminder IDs survive across sessions, unlike AppleScript URIs or CLI positional indexes.
- **Tool safety annotations** — every tool declares `readOnlyHint` / `destructiveHint` so Claude clients can auto-run queries but prompt for mutations.
- **Language-neutral** — the skill matches on intent, not keywords. Works identically in German, French, Spanish, Japanese, etc.
- **Speed** — full CRUD smoke-test completes in under 1 s on 300+ reminders across 10 lists.
- **Signed + notarized** — no Gatekeeper warnings; deployable via MDM.
- **100% local** — no network I/O. See [PRIVACY.md](PRIVACY.md).

## Usage examples

In Claude Desktop and Cowork the tools appear under **Apple Reminders**; in Claude Code the skill loads when you mention reminders. The examples below show the tool calls behind each answer.

### Example 1 — "What's on my plate today?"

> **You:** Was habe ich heute zu tun?
>
> **Claude** (invokes `get_today`):
> ```json
> { "status": "ok", "data": { "reminders": [
>   { "id": "A1B2…", "name": "Zahnarzt-Termin bestätigen", "list": "Persönlich", "due_date": "2026-04-14T10:00:00" },
>   { "id": "C3D4…", "name": "Rechnung #2026-0412 prüfen", "list": "Arbeit", "due_date": "2026-04-14T14:00:00" }
> ] } }
> ```
> **Claude:** Du hast heute zwei offene Erinnerungen: den Zahnarzt-Termin um 10:00 (Persönlich) und die Rechnungs-Prüfung um 14:00 (Arbeit).

### Example 2 — "Add a reminder to the groceries list"

> **You:** Remind me to buy oat milk tomorrow at 6pm.
>
> **Claude** (invokes `create_reminder`):
> ```json
> { "list": "Groceries", "title": "Buy oat milk", "dueDate": "2026-04-15T18:00:00" }
> ```
> **Response:**
> ```json
> { "status": "ok", "data": { "reminder": { "id": "E5F6…", "name": "Buy oat milk", "due_date": "2026-04-15T18:00:00" } } }
> ```
> **Claude:** Done — added "Buy oat milk" to Groceries for tomorrow at 18:00.

### Example 3 — "Clean up what's overdue"

> **You:** Show me everything that's overdue, then mark the Slack-DM one as done.
>
> **Claude** (invokes `get_overdue`):
> ```json
> { "status": "ok", "data": { "reminders": [
>   { "id": "G7H8…", "name": "Reply to Alex in Slack DM", "list": "Work", "due_date": "2026-04-12T17:00:00" },
>   { "id": "I9J0…", "name": "Review PR #482", "list": "Work", "due_date": "2026-04-13T12:00:00" }
> ] } }
> ```
> **Claude** (invokes `complete_reminder` with `id: "G7H8…"`):
> ```json
> { "status": "ok", "data": { "reminder": { "id": "G7H8…", "completed": true, "completion_date": "2026-04-14T18:22:01" } } }
> ```
> **Claude:** Two overdue items: Slack reply (now marked done) and PR #482 review (still open).

## Installation

### Claude Desktop / Cowork

Download `apple-reminders.mcpb` from [Releases](https://github.com/high5-ventures/apple-reminders-for-claude/releases) and double-click it. Claude Desktop shows an install dialog; click **Install**, then grant Reminders access in the macOS privacy prompt on the first tool call.

**Updating works exactly the same way** — download the newer `.mcpb` and double-click it.

This is how the extension is installed. The two sections below cover other MCP clients; on a Mac with Claude Desktop you do not need them.

### Claude Code (CLI)

```shell
/plugin marketplace add high5-ventures/apple-reminders-for-claude
```

Reload Claude Code before the next step; the plugin is not visible until the marketplace has been picked up.

```shell
/plugin install apple-reminders@high5-apple-reminders-for-claude
```

This path offers new versions automatically, but does not install them; you still confirm each update.

### Any other MCP client (Cursor, Zed, …)

```shell
npm install -g @high5ventures/apple-reminders-mcp
```

Then add it to your client's MCP configuration:

```json
{
  "mcpServers": {
    "apple-reminders": {
      "command": "apple-reminders-mcp"
    }
  }
}
```

Or skip the global install and let the client fetch it on demand:

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

The location of that file differs per client.

### Build from source

```shell
git clone https://github.com/high5-ventures/apple-reminders-for-claude.git
cd apple-reminders-for-claude
./build.sh
```

Produces `dist/reminders-eventkit` (universal binary for Apple Silicon and Intel), `dist/skill/` (Claude Code skill), and `dist/apple-reminders.mcpb` (Claude Desktop bundle). Builds are unsigned; see [CONTRIBUTING.md](CONTRIBUTING.md) for the signed release workflow.

Requirements for building: macOS 11+, Xcode Command Line Tools, Node.js 18+. Toolchains older than Xcode 15 also work; they compile without the macOS 14 permission API and fall back to the older request. To build only your own architecture, set `ARCHS`, e.g. `ARCHS=x86_64 ./build.sh`.

## Configuration

No configuration is required for normal use. The extension runs with these defaults:

| Setting | Default | Notes |
|---|---|---|
| Reminders permission | prompted on first use | Revocable in **System Settings → Privacy & Security → Reminders** |
| Binary timeout (Node wrapper) | 30 s | Hardcoded ceiling; well under any MCP client timeout |
| Response payload cap | 16 MB | Covers databases with thousands of reminders |

If you use the npm-distributed server with a non-standard MCP client, set `REMINDERS_BINARY` to the absolute path of the `reminders-eventkit` binary:

```shell
export REMINDERS_BINARY=/absolute/path/to/reminders-eventkit
```

The `.mcpb` and Claude Code plugin installations set this variable automatically.

## MCP tools

All 13 tools return a stable JSON envelope — `{ "status": "ok", "data": ... }` on success, `{ "status": "error", "code": "...", "message": "..." }` on failure.

| Tool | Annotation | Purpose |
|---|---|---|
| `get_lists` | read-only | List all reminder lists with open/completed counts |
| `get_list_info` | read-only | Metadata for one list by name or id |
| `list_reminders` | read-only | List reminders in a list (open/completed/all) |
| `search_reminders` | read-only | Full-text search across all lists |
| `get_today` | read-only | Reminders due today |
| `get_overdue` | read-only | Overdue open reminders |
| `get_scheduled` | read-only | All open reminders with a due date |
| `get_reminder` | read-only | Fetch one reminder by ID |
| `create_reminder` | additive | Create a new reminder |
| `update_reminder` | destructive, idempotent | Update an existing reminder |
| `complete_reminder` | destructive, idempotent | Mark as completed |
| `uncomplete_reminder` | destructive, idempotent | Unmark completed |
| `delete_reminder` | destructive, idempotent | Permanently delete |

"Destructive" here follows the MCP specification: it means the operation mutates existing state irreversibly from the user's point of view. Claude clients use these hints to decide when to prompt for confirmat