mcp-server-apple-reminders

Purpose

This MCP server is designed to provide native integration for Apple Reminders and Calendar on macOS. It interacts with system apps through the EventKit framework, enabling AI assistants (such as Claude) to read, create, update, and delete reminders, lists, subtasks, and calendar events in natural language.

Main Capabilities

Full CRUD Operations: Supports create, read, update, and delete for reminders, subtasks, reminder lists, and calendar events.
Priorities and Tags: Supports high/medium/low/none priorities, as well as tags and checklist subtasks with progress tracking.
Multi-condition Filtering: Can filter by completion status, due date range, priority, tags, full-text search, recurrence rules, location-based conditions, and more.
Flexible Date Formats: Accepts YYYY-MM-DD、YYYY-MM-DD HH:mm:ss(local time) or ISO 8601 format with time zone.
Native Integration: Two-way sync with Reminders.app / Calendar.app through EventKit; values configured in the system apps can be returned through read responses.
Automatic Permission Handling: Automatically discovers and prompts for macOS permission requests.
Unicode Support: Full support for Unicode characters, with input validation.
Structured Prompt Library: Provides multiple prompt templates through MCP's ListPrompts / GetPrompt endpoints, such as a daily task organizer, smart reminder creator, reminder review assistant, and weekly planning workflow.

Usage

Requirements

Node.js 20 or later
macOS (required by EventKit)
Xcode Command Line Tools (only required when building from source)
pnpm (recommended)

The published npm package includes a prebuilt, universal, code-signed bin/event binary, so using npx does not require the Xcode or Swift toolchain. Building from a git clone requires the tools mentioned above.

Installation and Configuration

Add the server to the MCP client. The npx form works for all clients; for a local build, replace command / args with the node command pointing to dist/index.js .

Claude Desktop configuration example (edit claude_desktop_config.json）：

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

Local build configuration:

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

After configuration, fully restart Claude Desktop (quit rather than just closing the window) for the changes to take effect.

Permission Notes

The built-in event CLI is launched through the bin/event-disclaim shim, declaring TCC responsibility at startup, so macOS attributes the permission request to event itself, rather than to the app that launched the MCP server. The first EventKit call prompts for authorization; after authorization it appears in "System Settings > Privacy & Security > Reminders / Calendar", and one authorization covers all MCP clients on the machine.

If the permission status is abnormal, you can run ./check-permissions.sh to reopen the dialog. If the permission dialog never appears and event does not appear in System Settings, you can run tccutil reset Calendar and tccutil reset Reminders to reset the TCC entries, then trigger the permission request again in the Claude conversation.

Headless/launchd Operation

When running in a non-GUI session (SSH, launchd agent/daemon), the first EventKit call may block indefinitely while waiting for a permission prompt that cannot be rendered. The server will terminate event calls exceeding 30 seconds (SIGKILL) and return a readable error. The timeout can be adjusted through the environment variable EVENTKIT_CLI_TIMEOUT_MS (milliseconds; invalid/zero values fall back to the default; the timeout cannot be disabled). The built-in event CLI also fails quickly in a non-GUI session and gives up on an unanswerable prompt after 15 seconds (EVENT_PERMISSION_TIMEOUT_MS).

macOS 26 (Tahoe) Build Issues

If pnpm build fails with the message could not build module 'Foundation', indicating that the Swift toolchain version is too old and requires Swift 6.3 or later. This can be resolved by installing Xcode 26.x or later Command Line Tools.

Use cases

Manage personal reminders and calendar events through an AI assistant.
Automatically create, review, and optimize reminders.
Generate daily execution blueprints or weekly plans, and automatically create calendar time blocks.
Integrate Apple Reminders and Calendar in MCP-enabled clients (Claude Desktop, Codex Desktop, Cursor, terminal clients, etc.).

Limitations

Read-only fields: Alarms, recurrence rules, location triggers, structured locations, calendar url / availability / isAllDay, and cross-calendar moves cannot be written through this server; they can only be configured and read from Reminders.app / Calendar.app.
Attendee updates: Require the Calendar.app scripting interface, which needs automation authorization and a GUI session, and does not support headless operation; they must be updated separately and cannot be merged with other fields; two events with the same title and start date will be rejected rather than guessed.
Single event deletion (occurrenceDate): Requires iCloud credentials (ICLOUD_APPLE_ID and ICLOUD_APP_PASSWORD or Keychain), and applies only to events synced with iCloud.
URL schemes: Accepts any valid URI scheme (http, https, mailto, tel, obsidian, shortcuts, etc.), but rejects dangerous schemes such as file, javascript, and data; http(s) hostnames are checked against an SSRF blacklist.
Platform limitations: macOS only.
Headless environments: Permission prompts cannot be rendered, which may cause blocking; although there is a timeout mechanism, functionality is limited.

Development commands

pnpm build — TypeScript + built-in event CLI (required before running from source)
pnpm build:ts — TypeScript only
pnpm build:event — built-in event CLI only (swift build -c release → bin/event）
pnpm build:release — build plus notarization (release packaging)
pnpm test / pnpm test:ci — Jest test suite / with coverage
pnpm lint — Biome format/fix + TypeScript type checking
pnpm check — lint + tests with coverage