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?

| Feature | Other Calendar MCPs | che-ical-mcp | |---------|---------------------|--------------| | Calendar Events | Yes | Yes | | Reminders/Tasks | No | Yes | | Reminder #Tags | No | Yes (MCP-level) | | Multi-keyword Search | No | Yes | | Duplicate Detection | No | Yes | | Conflict Detection | No | Yes | | Batch Operations | No | Yes | | Local Timezone | No | Yes | | Source Disambiguation | No | Yes | | Create Calendar | Some | Yes | | Delete Calendar | Some | Yes | | Event Reminders | Some | Yes | | Location & URL | Some | Yes | | Language | Python | Swift (Native) |

---

All 29 Tools

<details> <summary><b>Calendars (4)</b></summary>

| Tool | Description | |------|-------------| | list_calendars | List all calendars and reminder lists (includes source_type) | | create_calendar | Create a new calendar. A title is 1 to 255 characters and not only whitespace, also on update_calendar, and type is event or reminder. The limit is not a promise that a long title stays: a 255-character title was among those list_calendars stopped showing in one run (#449). If saving a reminder list reports an error but the list turns out to be saved, the call succeeds; if whether it was saved cannot be checked, the list is kept and the call fails with an error that says how to check before creating it again (#289); fields the store holds differently are listed in store_differs with a note, and creating it again with the same parameters may make a second copy (#261) | | delete_calendar | Delete a calendar or reminder list (not undoable). require_empty: true refuses one that holds any event (checked only about 200 years either side of now; a passed check returns checked_empty, searched_from / searched_to) or any reminder (#328) | | update_calendar | Rename a calendar or change its color (v0.9.0) |

</details> <details> <summary><b>Events (4)</b></summary>

| Tool | Description | |------|-------------| | list_events | List events with filter/sort/limit (v1.0.0) | | create_event | Create an event (with reminders, location, URL, per-event timezone, recurrence with excluded dates) | | update_event | Update an event (including timezone, recurrence, span for recurring) | | delete_event | Delete an event (with occurrence support for recurring) |

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: <id> (a row error in the batch tools) instead of ending the server. Without Reminders access EventKit may not report the item as a reminder; the event lookup's Objective-C exception is then caught, and the tool answers that the lookup failed and the event may still exist (#288). That was measured with the kind check switched off, and a run with Reminders access actually denied has not been done. The check itself (calendarItem(withIdentifier:)) is not wrapped, so if it raises there, the process can still end (#293).

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.

</details> <details> <summary><b>Reminders (8)</b></summary>

| Tool | Description | |------|-------------| | list_reminders | List reminders with filter/sort/limit, tags extraction (v1.0.0) | | create_reminder | Create a reminder with due date, tags (v1.3.0); a bare YYYY-MM-DD due date makes it date-only (#267); with a due date, bare or timed, the response carries date_sync with aligned judged on the saved reminder (#301, #308; a timed due that lost its time zone on save is written again and saved a second time, as update_reminder does). If the save reports an error but the reminder turns out to be saved, the call succeeds; fields the store holds differently are listed in store_differs with a note, and creating it again with the same parameters may make a second copy (#261); a save that failed and could not be checked keeps the reminder and fails with an error that says how to check before creating it again (#289) | | update_reminder | Update a reminder (including tags, clear_due_date) (v1.3.0) | | complete_reminder | Mark as completed/incomplete | | delete_reminder | Delete a reminder | | search_reminders | Search reminders by keyword(s) or tag (v1.3.0) | | list_reminder_tags | List all unique tags with usage counts (v1.3.0) | | cleanup_completed_reminders | Delete all completed reminders in one call, dry_run preview by default (v1.7.2); one undo recreates what it deleted (#243) |

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.

Arguments are checked against the schema (#448): every tool refuses a key it does not read, and a value that is not the declared string, integer, number, array or object, with nothing done; the elements of an array of strings or integers are checked too. The message lists the accepted keys. A batch row fails alone. On a declared key this check treats JSON null as absent, though a handler may still refuse it (limit, for one); on an undeclared key it is refused like any other value.

recurrence keys are checked (#434): create_event, create_events_batch, update_event, create_reminder and update_reminder refuse any key i