macOS Calendar and Reminders

che-ical-mcp

Give Claude native control of macOS Calendar and Reminders. A Swift MCP server built directly on EventKit — 29 tools for events, reminders, tags, batch operations, conflict detection, and undo/redo. Not just calendar events: it drives Reminders and tasks too.

English | 繁體中文

---

Install

Claude Code — register this repo as a marketplace, then install the plugin. The plugin bundles the /today, /week, /quick-event, /remind slash commands and a PreToolUse hook that verifies day-of-week on every event write:

claude plugin marketplace add PsychQuant/che-ical-mcp

claude plugin install che-ical-mcp@che-ical-mcp

Claude Desktop — download the latest .mcpb from Releases and double-click to install.

Standalone MCP — the 29-tool server on its own, no plugin extras:

mkdir -p ~/bin

curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP && chmod +x ~/bin/CheICalMCP claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP

On first use, macOS prompts for Calendar and Reminders access — click Allow. Building from source, upgrading in place, or running under SSH / launchd / VS Code? See Installation for the full guide.

---

Why che-ical-mcp?

---

All 29 Tools

Calendars (4)

Events (4)

A reminder's identifier given to an event tool (#260): update_event, delete_event, copy_event, move_events_batch and delete_events_batch answer Event not found: (a row error in the batch tools) instead of ending the server. Without Reminders access EventKit may not report the item as a reminder, and the lookup can still end the process (#288); a reminder's identifier normally comes from the reminder tools, which need that access.

Recurrence exclusions (#182): create_event (and each create_events_batch item) accepts recurrence.excluded_occurrence_dates to skip specific dates in a recurring series at creation time — applied with best-effort all-or-nothing semantics (any failure removes the entire new series via compensating delete; rollback failure is reported, never silent; the first occurrence cannot be excluded), and one undo removes the whole series including exclusions. The excluded dates are removed occurrences, not edited ones (checked on iCloud only, 2026-10-05; other stores were not checked), so they do not stop that undo; an occurrence edited on its own after the series was created does (#236). Known limitation: on idempotent retry, a duplicate recurring series with every requested date already absent is skipped, but extra exclusions already present on the existing series (beyond those requested) are not detected.

Reminders (8)

Recurring reminders (#194): list/search include has_recurrence, complete public recurrence_rules, and precision-aware due. Completion adds operation (write outcome) and next_occurrence (confirmed/unknown/not_applicable). Use operation.status rather than legacy is_completed: a successful completion may leave the next occurrence incomplete. Unknown successor information must not trigger a second write. A different-ID or unconfirmable successor is reported as unknown, never as the series having ended. Undo of a recurring completion is identity-guarded (#204): once the identifier no longer resolves to the recorded occurrence it refuses explicitly and drops its history entry instead of jamming the stack. Breaking (#205): completed must be a JSON boolean on complete_reminder / list_reminders / search_reminders — strings and numbers are rejected; omit or null keeps the old meaning. Breaking (#207, unreleased): the same contract now applies to every boolean tool argument (all_day, clear_*, include_completed, dry_run, delete_original). See response contract and limitations.

Rescheduling reminders (#227/#235/#237): In the rows measured, the Reminders.app list showed a reminder's earliest time-based alarm (#433), so update_reminder with a timed due_date moves the start date and every absolute-date alarm along with the due date (a bare date makes the reminder date-only instead, see below; by calendar days when the old due date has no time; otherwise by the exact difference). clear_due_date also clears the start date and removes absolute-date alarms. A move keeps any offset that already exists, so to repair a reminder whose alarm already disagrees with its due date pass realign_to_due: true (with due_date, or alone for the current due date; relative alarms stay, so an early relative alarm still sets what the list shows): the earliest absolute-date alarm lands on the due date, later ones keep their spacing after it, and the start date is set to the due date unless it already agrees with it (any time on its day for a date-only due; the due time, or its day at midnight or without a time, for a timed due). The response reports what moved in date_sync, and date_sync.aligned says whether, on the saved reminder, the start date and the earliest absolute-date alarm agree with the due date (an alarm set apart on purpose also reads false). A timed due date written to a floating reminder, such as a date-only one made in Reminders.app, keeps its explicit time zone. Undo restores the start date and alarms, location alarms included (#228).

Alarms after completing a repeating reminder (#423): completing a repeating reminder that has a location trigger leaves one plain relative alarm at 0 minutes (no location) on the next occurrence and on the completed copy (measured on iCloud; it does not appear without a location trigger, without recurrence or without a completion, and a later completion does not add another, whether the alarm is still there or was removed). Completing a reminder sets only the completion fields; EventKit or the store adds this alarm when that save rolls the reminder over, and which of the two was not told apart. After a confirmed rollover complete_reminder reads the next occurrence back and reports its relative alarms as next_occurrence.alarms_minutes_offsets, with alarms_note naming any that appeared on that read and were not there before the completion (an alarm from another app or a sync would look the same). When the next occurrence cannot be re-read, or changed in between, next_occurrence.alarms_read_back is false with alarms_read_back_note and no alarms are reported. With any other next_occurrence.status these fields are absent. Nothing is written (a default: removing the alarm was not chosen, since its purpose is unknown); update_reminder with alarms_minutes_offsets removed it in the cases tried. Whether it fires and whether Reminders.app shows it are not checked. The completed copy gets a new identifier and is not read.

`recurrence` keys are checked (#434): create_event, create_events_batch, update_event, create_reminder and update_reminder refuse any key in recurrence other than frequency, interval, end_date, occurrence_count, days_of_week, days_of_month and, on the two create-event tools, excluded_occurrence_dates, and write nothing for that item. Such a key used to be ignored, so count in place of occurrence_count created a series that never ends. The same tools refuse, and write nothing for that item: end_date together with occurrence_count; a non-empty days_of_month on a daily or weekly rule, which EventKit stores but does not use (measured on iCloud; monthly and yearly rules use it, and every frequency uses days_of_week); and any key of recurrence, or a read tool's recurrence_rules, event_recurrence_rules or reminder_recurrence_rules beside recurrence instead of inside it.

A rule belongs to the series (PR #439): update_event refuses recurrence or clear_recurrence on one occurrence (occurrence_date with span this) and clear_recurrence with occurrence_date and span future