Apple Reminders MCP

apple-reminders-mcp is an MCP-first, local-first server for Apple Reminders on macOS. It exposes Apple Reminders lists and reminder operations through MCP tools backed by the local Mac's EventKit access.

The package is MCP-first and not Codex-only. Codex is a first-class example consumer, and any MCP client that can launch a stdio server can use the same executable and tool protocol.

This package is macOS-only because Apple Reminders access comes from EventKit on the local Mac. It does not provide cross-device sync, cloud coordination, or a remote Reminders API. macOS privacy controls still own Reminders authorization for the helper app.

Package Boundary

The standalone package owns the public package infrastructure: the apple-reminders-mcp executable, MCP tool schemas, helper discovery, and the local Apple Reminders helper host identity. Consumer-specific glue lives outside this package. Sugar is one consumer of the package; Sugar is not a prerequisite.

The package name is @motionsmith/apple-reminders-mcp.

After the package is published, a standalone consumer should install it with:

corepack pnpm add @motionsmith/apple-reminders-mcp

During private incubation, install from a packed local artifact instead.

Install From A Packed Artifact

From the repository checkout, create a package artifact:

PACK_DIR=$(mktemp -d /tmp/apple-reminders-pack.XXXXXX)
corepack pnpm pack --pack-destination "$PACK_DIR"

Install it into a clean consumer root:

CONSUMER_DIR=$(mktemp -d /tmp/apple-reminders-consumer.XXXXXX)
cd "$CONSUMER_DIR"
npm init -y
corepack pnpm add "$PACK_DIR"/*.tgz

No live Reminders write is required for install, server startup, or MCP tool discovery.

Run The MCP Server

Start the stdio MCP server through the package executable:

corepack pnpm exec apple-reminders-mcp

Consumer MCP configuration can point directly at the executable:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "apple-reminders-mcp",
      "args": []
    }
  }
}

The package exports the same command through appleRemindersMcpPromptContext() and appleRemindersCodexSdkMcpConfig() for consumers that generate MCP config programmatically.

Codex Example

Register the standalone MCP server with Codex:

codex mcp add apple-reminders apple-reminders-mcp

Equivalent config:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "apple-reminders-mcp",
      "args": []
    }
  }
}

Codex/OpenAI approval and macOS Reminders authorization are separate layers. Codex may ask before calling a tool, and macOS may ask before EventKit allows the helper app to read or write Reminders.

Helper And Permission Setup

The MCP server uses the package-owned Apple Reminders helper protocol. Helper discovery checks these paths in order:

1. An explicit helper path supplied by an embedding caller.
2. bin/Apple Reminders MCP Host.app/Contents/MacOS/apple-reminders-helper.
3. bin/apple-reminders-helper.
4. scripts/apple-reminders-helper.swift for source-checkout development only.

The app bundle path is the preferred standalone host identity because macOS Reminders permission is granted to the host app:

• app bundle: bin/Apple Reminders MCP Host.app
• display name: Apple Reminders MCP Host
• executable name: apple-reminders-helper
• bundle identifier: com.motionsmith.apple-reminders-mcp.host

For permission setup and status, use list_reminder_lists as the first EventKit-backed discovery tool. If macOS Reminders access is missing or denied, the tool returns a structured provider_authorization_missing error with recovery text. Grant Reminders access to Apple Reminders MCP Host in macOS privacy settings, then retry list_reminder_lists.

When the helper is absent, MCP tool calls return a structured helper_missing error with recovery text naming Apple Reminders MCP Host.

Tool Discovery Smoke Test

After installing the artifact in a clean consumer root, verify the executable starts and can list MCP tools without touching live Reminders data:

corepack pnpm exec apple-reminders-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Expected results:

• initialize returns MCP server info for apple-reminders.
• tools/list returns the six Apple Reminders tools: list_reminder_lists, read_reminders, create_reminder, update_reminder, complete_reminder, and reopen_reminder.

First Safe List And Read Test

List discovery is the first safe EventKit-backed test. It may require macOS Reminders permission, but it does not create, update, complete, or reopen any reminders:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_reminder_lists",
    "arguments": {}
  }
}

Expected success shape:

{
  "lists": [
    {
      "name": "Inbox",
      "id": "calendar-id"
    }
  ]
}

After choosing a list returned by list_reminder_lists, a safe read test can call read_reminders for that explicit list. Do not create, update, complete, or reopen any reminders as part of a read test.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "read_reminders",
    "arguments": {
      "listName": "Inbox",
      "includeCompleted": false
    }
  }
}

Explicit Create Example

Live Reminders mutation:

The next example writes to the local Mac's Reminders data. Use it only with a list name that came from list_reminder_lists and only after the local operator explicitly approves this live write.

Expected create_reminder input:

{
  "listName": "Inbox",
  "title": "Buy milk"
}

Expected success shape:

{
  "action": "created",
  "id": "reminder-id",
  "calendarId": "calendar-id",
  "calendarName": "Inbox"
}

An idempotent create may instead report "action": "deduplicated" when the package finds an existing reminder for the same idempotency key.

Structured Failures

Tool failures are returned as structured MCP tool errors. The error text should name the code, the observed problem, and a recovery action.

Expected error codes:

• helper_missing: the helper app or executable is not installed at the resolved path. Install or build Apple Reminders MCP Host.app, then retry.
• provider_authorization_missing: macOS Reminders permission is missing, denied, restricted, or not sufficient for the requested operation. Grant Reminders access to Apple Reminders MCP Host.
• list_not_found: the requested list name is not available. Run list_reminder_lists, then retry with an available list name.
• unsupported_host: the server is running on a non-macOS host. Run it on the Mac that owns the Reminders data.
• provider_error: EventKit or the helper failed for another provider reason. Check the helper app health and retry with a known list.

Notices

This package is not affiliated with Apple or OpenAI. Apple Reminders, macOS, and EventKit are Apple platforms and APIs. Codex and OpenAI are separate products and services.

Do not publish npm-facing docs or package artifacts until the private visibility and license decision has been replaced by an explicit public release policy.