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) |
Calendars (4)
| 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). Not undoable (#273): undo after it is refused and the entry discarded, so the next undo reverts the operation recorded before it |
delete_calendar | Delete a calendar or reminder list. This cannot be undone: it deletes every event or reminder in it, and undo after it is refused and the entry discarded, so the next undo reverts the operation recorded before it (#273). 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). Not undoable (#273): undo after it is refused and the entry discarded, so the next undo reverts the operation recorded before it; run update_calendar again to revert |
Events (4)
| 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. On that retry, an occurrence edited on its own that starts on an excluded date is a conflict, with an error of its own that says an edited occurrence starts on that date (#534: it answered skipped, because such an occurrence has an identifier of its own). It is recognised by that identifier, the series' identifier followed by /RID= (as on iCloud; Exchange was not measured), and it counts whether it was edited in place or moved onto the date. Not detected, so the retry answers skipped: an occurrence that was moved off the excluded date, and an edited occurrence whose identifier has another shape.
Reminders (8)
| 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.
Coordinates, radius, proximity and priority are checked (#473): structured_location (create_event, update_event, each create_events_batch row) and location_trigger (create_reminder, update_reminder) refuse a latitude outside -90 to 90, a longitude outside -180 to 180, and a radius of 0 or less; structured_location also refuses one coordinate without the other (give both or neither). location_trigger.proximity is required and must be exactly enter or leave. priority on create_reminder, update_reminder and each create_reminders_batch row must be an integer from 0 to 9; EventKit refused 10, -1 and 100 (measured on iCloud; Apple documents 0 to 9), so it is refused here before anything is written, not clamped, and JSON null counts as omitted on all three. Before, a radius of 0 or less became 100 or was dropped, half a coordinate pair was dropped, and any proximity other than leave (Leave, exit, none) was written as enter, all with no message. A batch row fails alone. A string array element that reads as a data URL (text starting data: with a comma) is refused with the same explanation a string argument gets.
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.
Moving a series, and span future from a later occurrence (#451): two closed rules on a series that has started, checked before anything is written; otherwise occurrences that happened would be gone, moved to days they never had, or added in the past, and undo refuses it (measured on iCloud). From an occurrence that has happened (the first for span all or span future from it, the one named for span future from a later one), start_time may change only the time of day, on that occurrence's own date; any other date, earlier or later, is refused. From an occurrence still to come, and on a series that has not started, a start before now is refused. A recurrence from an occurrence that has happened must keep the stored pattern (frequency, interval, days_of_week, days_of_month) with its own bound, or, while the series has occurrences to come, no bound, an end_date at or after now, or an occurrence_count at least the stored one. On a series with an occurrence_count, a bound other than its own passes only with span all (or span future from the first occurrence) while the first occurrence is not deleted, on a rule with one slot a period; an end_date before now is refused. To change other fields, leave start_time and recurrence out; to move or change the rule from an occurrence still to come, use span future with its occurrence_date. A timezone other than the event's, or clear_timezone on an event that has a zone, from an occurrence that has happened is refused too (#478): the store repeats the occurrences at the new zone's wall-clock time, which moved happened ones across a daylight-saving change and lost the last one of a counted series (measured on iCloud); span future from an occurrence still to come (not where the series' first occurrence was edited on its own, or deleted with the first one left edited on its own: there no identifier takes it yet) kept the earlier occurrences for timezone; no route for clear_timezone was measured. Only the event's own identifier (item_timezone) counts as no change, and it is not written again; another spelling of the same zone, such as ROC for Asia/Taipei, is a change, and so is any zone, this Mac's included, on an event with no zone of its own (item_timezone null). These rules cover start_time, recurrence, timezone and clear_timezone only: a one-off event in the past given a rule repeats from its day, adding occurrences between it and now; clear_recurrence with span all deletes the occurrences after the first (#439); and #442 and #455 are open. A weekly rule repeating every two weeks or more with a week start other than Monday counts as one recurrence cannot write when that week start splits its days and the series' first weekday between two weeks that Monday would keep together, or the reverse (a rewrite gets Monday and would move occurrences by a week): on a started series its rule is not changed from an occurrence that happened. Biweekly Tuesday from a Tuesday start is not affected, nor, with a Sunday week start (as Google writes it), Tuesday and Thursday. From a later occurrence over such a rule, calendar_name is refused with or without recurrence. From a later occurrence with span future, all_day and occurrence_count are refused, since occurrences went, and so is calendar_name alone, which moved the earlier occurrences too; from an occurrence still to come a rule with end_date or no bound, with start_time or with calendar_name, stays within the later occurrences (measured on iCloud).
A time change over a series with a deleted occurrence (#503): on iCloud, changing the start, end, all_day or time zone of more than one occurrence of a series (span all, or span future) brought back every occurrence deleted on its own among them (a time zone across a daylight-saving divergence), and undo cannot remove them again. Such a write is now refused before anything is written while one of those occurrences was deleted on its own, or while that cannot be ruled out: a series the check cannot list whole and does not check up to the horizon in the next paragraph (#506), a series read through its series' id after its first occurrence was deleted, or a rule the check does not follow (each refusal names the condition that applies). A recurrence written over several occurrences with another pattern (frequency, interval, days or count) goes through the same check, since whether it keeps the deletions was not measured (only a new end_date was, and it kept them), and so does a series with more than one rule; a weekly rule without days counts as the weekday of the series' original first slot, a monthly one as its day. So does writing the first occurrence's shown time back over the whole series when that occurrence was edited on its own, since its shown time is not the series' time. A change of the title, notes, location, url, alarms or structured_location, or a new end_date alone, is not affected: on iCloud these kept the deletions with span all and with span future from a later occurrence, before and after it (url, alarms and structured_location through an occurrence's own id on a count series only), and so did a new end_date together with a calendar of the same account from a later occurrence. On a series the check can follow to its end, or up to the horizon in the next paragraph from that occurrence, and for a change that is not all_day, span future with the occurrence_date of an occurrence after the last deleted one, not edited on its own, changes the time from there on, and the earlier deletions stay deleted (measured for a new start alone; not measured for an end alone, a time zone, or a new start together with a time zone or a rule; a new rule pattern gets no route, and neither does a write that also moves the series to another account, which checks every occurrence from any one, or one through the first occurrence's own id); on any other series no update route keeps the deletions. A whole series moved to a calendar of another account (calendar_name with span all, or move_events_batch) is a create plus a delete; whether it keeps the deletions was not measured, so it goes through the same check and is refused while one is found or cannot be ruled out. With span future from a later occurrence, every occurrence of the series is checked, not only those from it on. An all-day series whose rule end falls less than a day after an occurrence's start is not followed either (how EventKit reads that end was not measured). Other stores were not measured.
A series the #503 check cannot list whole is checked up to two years from now (#506): an open-ended series, one that ends about five years or more after its start, and a count series whose end the check cannot place (a count with days of the month, a monthly or yearly count from the 29th to the 31st, a long weekly count on several days) cannot be listed whole, so #503 refused every change of their start, end or time zone over more than one occurrence. Now such a change goes through when no occurrence deleted on its own is found among the occurrences the write reaches and the listing reaches the horizon, now plus two years on the wall clock of the series' time zone, without a gap from the first occurrence the write reaches. The series is listed from about a year before its first occurrence to about five years after it, and, when that ends before the horizon, also around now, from about four years before to about three years ahead; a series begun more than about nine years ago leaves a gap between the two, so a change over the whole series is still refused there (span future from an occurrence near now can pass). The response then adds deleted_occurrences_checked_until, the date before which every occurrence the write reaches was compared (at or after the horizon), and deleted_occurrences_note. This check is not complete: an occurrence deleted on its own on or after that date is not checked and comes back with the write, and undo does not remove it (the risk the maintainer accepted on 2026-11-12). A move to a calendar of another account, a new rule pattern and an all_day change still need the whole series listed: through the series' id #442 refuses all_day on an open-ended series, and through the first occurrence's own id (#428), where #442 does not apply, #503 refuses it because the listing does not cover the series. For a change of the start, end or time zone in the same account, a bounded series begun about three to nine years ago that ends within about three years is now listed whole, the window around now joining its first-start listing, so it answers as any series the check covers, without the two fields. If the rule would give more than 20,000 occurrences between the first one and the end of the listing (a daily series begun about 55 years ago), the check refuses instead of comparing part of them. Measured on iCloud with --cli (2026-11-12, weekly 10:00 series in Asia/Taipei moved to 15:00 with span all): with no deletion, an open-ended series begun this week went through with the same 104 occurrences up to the horizon and deleted_occurrences_checked_until about five years out, and one begun five years ago went through checked about three years out; a deletion inside the horizon, and one past the horizon but inside the listing, refused and wrote nothing; a series begun ten years ago was refused for span all and went through for span future from next week; and an occurrence deleted on its own past the listing (about five years out) came back with the write, which is the accepted risk. The extra listing of a daily series begun eight years ago made the call take about 6 s, against about 2 s for one begun this week (#520 removed the scans that took that time: on 2026-11-13 the same two calls took 0.32 s and 0.21 s, against 5.81 s and 2.07 s on main that day; each figure is the wall clock of one whole --cli process, the median of three runs, on a disposable calendar holding only the series, presumably iCloud, as its source was not read back; the CHANGELOG entry for #520 gives the ranges and the builds; #527 then made the #503 baseline and the check for deleted occurrences read one listing where they list the same dates, and left the call's other listings as they were: several of them list those same dates on their own when their checks run, among them the #509 rule-end check when it needs the series' first slot (sharing that one is #533). #527 was timed in a separate session on 2026-11-13, on iCloud: other disposable calendars, another time of day, six runs per figure (three in each of two rounds, the two binaries interleaved) against three above, and a machine load that was not recorded in either session, so its figures compare with each other and not with the 0.32 s and 0.21 s above. There the call on a series begun that week took a median of 0.36 s before and 0.26 s after, and the call on a series begun eight years ago, for which the two still list different dates, did not move: 0.46 s before and 0.48 s after. The CHANGELOG entry for #527 gives the rounds and the calendar with other series). Those runs used a build made before this change's two review fixes. Some of this was measured again on the merged code (b226968, 2026-11-12; the disposable calendar's source was not read back, presumably iCloud): a write with no deletion went through with its occurrences unchanged in number (an end-only change, a zone change on a series not yet started, and a start change through a first occurrence edited on its own; the plain start change above was not repeated; these three were used instead); a deletion inside the horizon was refused with nothing written, under those same writes; and the series begun ten years ago was again refused for span all and went through for span future from next week. The series begun five years ago, the deletion past the horizon inside the listing, the deletion past the listing and the timings were not measured again on that build (see #520 for timings on main).
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, and writes nothing. In every release from v1.5.0 (measured on iCloud on v1.22.0, read at the other tags), a rule saved on one occurrence deleted the rest of the series, clear_recurrence with span future left only one event on the series' first day, and clear_recurrence with span this detached the occurrence as a one-off and left the series repeating. Use span all for the whole series, and span future with occurrence_date to change a rule from that occurrence on. To end a series at an occurrence, pass span all and recurrence with the series' whole rule and an end_date after that occurrence's start, such as 23:59:59 that day: a bare date ends before that day's occurrence, and later occurrences go, also one edited on its own (measured on iCloud). On a series that has started, an end_date before now is refused (#451). clear_recurrence with span all leaves one event on the first day and deletes the other occurrences. An id of the form <series>/RID=<n>, one occurrence edited on its own, is told the series' id. recurrence with clear_recurrence is refused too.
A start move that would push an occurrence past the rule's end is refused (#509): a series' rule end is a fixed time, and update_event with a new start_time over the rest of the series (span all, or span future, which splits it) re-expands the rule up to that same time, so an occurrence whose new start falls after it was dropped, with updated, and undo cannot bring it back (measured on iCloud: an end at the last occurrence's start, which deleting the last occurrence on its own leaves, lost it with any later time). Measured too: a time zone change across a daylight-saving change (a New York series moved to UTC lost its last occurrence), a plain monthly series moved to the next month, and the series' rule passed again in the call with the same end. Such a write is now refused and writes nothing; the refusal names the occurrence, the end and the latest start it may get. The occurrences near the end are listed, an occurrence edited on its own counted by its original slot; when the series or those occurrences cannot be read, listed or placed, the write is refused too, as is a start moved later by more than a year and any start or zone change on an all-day series with an end (how an all-day rule's end compares with its days was not measured); so are a listing that finds none of the series' occurrences near the end, a rule with weeks of the year or set positions and no day, and a monthly or yearly series whose day comes from its start (no days of its own; months of the year alone count as none) and whose start is or would be on the 29th, 30th or 31st (such a rule skips a month without that day, which the check cannot follow), and an all_day change counts as a move (the month-end refusal applies whether or not the series has an end instant, #513: an open-ended series, or a counted one starting on the 29th to 31st, was already refused by #503, so the new refusals are a series bounded by occurrence_count whose start moves from the 28th or earlier onto the 29th to 31st, as a time zone change alone can do, such as 05:00 Tokyo on the 1st to Los Angeles, and a series with an end given a rule with occurrence_count or no end in the call; a new time of day on the same day counts when the start is on the 29th to 31st; not measured, and such a series is changed in Calendar); so is a write through the series' identifier over the whole series when the original slot of its first occurrence cannot be shown (a first occurrence moved on its own shows its moved time, and the check reads the move from the slot too); these refusals point to Calendar. A recurrence passed in the call is checked against its own end_date. To make the move, pass the series' rule in the same call as recurrence, with an end_date at or after that new start: measured to keep every occurrence on a weekly series. That call can still be refused by #503 when an occurrence of the series was deleted on its own. Through an occurrence edited on its own (#416) a call cannot also pass the rule, so that refusal points to Calendar, as it does for a rule with days of its own (an end late enough for every reading can bring in an occurrence the series never had), when the occurrence the write starts from was moved on its own (for the same reason), for a series whose rule ended after an occurrence happened (#451 refuses a later end), and through a series whose first occurrence was deleted (#326). A new start after the end is refused with the same route, once the occurrences near the end are listed (a move of more than a year, or a listing that fails, gets that cause instead); from the last occurrence before the end it points to span this (on one of the series' weekdays for a weekly rule with days of the week, #454). On a timed daily or weekly series, a time zone change between zones without daylight saving kept the instants and is not refused (a monthly or yearly one is refused when its start falls on the 29th to 31st in either zone); an earlier move that would bring in an occurrence after the end, and an occurrence edited on its own and moved more than a year from its slot, are not checked. A series with occurrence_count given a far later end_date in the same call as a new start is refused as having no occurrence near that end (known limit; a later end only adds occurrences).
The start has to be on days_of_week (#454): create_event, create_events_batch and update_event refuse a start off the list on every frequency, not only weekly, and write nothing. On daily, monthly and yearly it used to leave a stray first occurrence (measured on iCloud). On update_event this covers a rule in the call and, on span all and future, the series' own rule. An update that leaves the start's day where it is passes on a series already off its days. Moving one occurrence of a non-weekly series on span this is not refused. A rule on a numbered weekday, such as the first Monday of the month, cannot be written by this tool, so such a series is told to change in Calendar.
The start has to be on days_of_month too (#461): on monthly and yearly rules, create_event, create_events_batch and update_event refuse a start that is not one of the rule's days_of_month, by the same rules as days_of_week, and write nothing; with no recurrence in the call, changing the start's date of such a series on span all or future is refused, on the list or off it (a move to another of its days put two occurrences on one day); on span all the message names the route measured for a monthly series (recurrence with every field of the rule, and start_time), on span future, span all or Calendar; and Calendar when the rule has a part recurrence cannot write. Span this on one occurrence is not checked. Measured on iCloud, such a start used to become a stray first occurrence, and moving a series' start onto another day made that day part of the rule. Reminders are not checked.
occurrence_count on a yearly event rule with days_of_week (#444): on a rule with interval 1 and no days_of_month, the store does not count occurrences, so 6 gave 22 (measured on iCloud). create_event, create_events_batch and update_event refuse a count there, even 1, and write nothing. For those days, use monthly with interval: 12, which holds the count, except that a count from a later occurrence with span future is refused (#443), or end_date. For once a year, use yearly without days_of_week. A yearly rule with days_of_week repeats in the start's month. interval above 1 and a non-empty days_of_month are not refused: the count held. The reminder tools are unchanged: there the count held.
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, and writes nothing. In every release from v1.5.0 (measured on iCloud on v1.22.0, read at the other tags), a rule saved on one occurrence deleted the rest of the series, clear_recurrence with span future left only one event on the series' first day, and clear_recurrence with span this detached the occurrence as a one-off and left the series repeating. Use span all for the whole series, and span future with occurrence_date to change a rule from that occurrence on. To end a series at an occurrence, pass span all and recurrence with the series' whole rule and an end_date after that occurrence's start, such as 23:59:59 that day: a bare date ends before that day's occurrence, and later occurrences go, also one edited on its own (measured on iCloud). clear_recurrence with span all leaves one event on the first day and deletes the other occurrences. An id of the form <series>/RID=<n>, one occurrence edited on its own, is told the series' id. recurrence with clear_recurrence is refused too.
A failed reminder write does not land later (#274, #459): a commit of an existing reminder or reminder list can fail and stay pending in the store it was made on, where that store's next save of anything writes it (measured on iCloud, with a failure induced for the test; no ordinary use was found that causes one). Since #459 these writes (an update, a completion, a deletion, a list rename or recolor, a list deletion, and the undo and redo that change or remove an existing reminder) commit on a separate store that is dropped after the call, so a failure is dropped with it and answers as a plain error; the server's long-lived store never holds it (measured 2026-11-09 for an update and a batch row; inferred for the others). Only the fields the call changed or names are written, so a change made elsewhere to another field is kept, also by its undo (shown by in-memory tests; on device the server's cache had already caught up). Alarms count as three fields, relative, absolute and location, so alarms_minutes_offsets keeps an absolute or location alarm added elsewhere. A completion of a repeating reminder that another app moved on to another occurrence since the server read it is refused, with nothing written. An undo or redo of an update_reminder, a keep_later_edits merge or a completion is refused the same way, with the entry kept. The undo of a deletion recreates the reminder, a create, on the long-lived store. A batch call shares one such store and drops it after a row fails. At most 4 are open at once; a call that would need a fifth is refused (writeStoreBusy). If that store cannot read the item by its identifier, the call fails with a store error, not "not found". Each such write costs about 45 ms more. Creates, including the second save of a due date (#237, which answers date_sync.aligned: false with no error, and where what may land is the date asked for), and all event writes stay on the long-lived store; events and event calendars did not keep failed writes pending.
Changing a reminder's recurrence (#354): update_reminder accepts recurrence (the object create_reminder takes, without excluded_occurrence_dates), which replaces the reminder's rule, and clear_recurrence: true, which removes it; the identifier, completion history and alarms stay. A rule change does not move the due date (a default, which can be revisited): measured on iCloud, after a weekly Thursday reminder is changed to Friday its pending occurrence stays on Thursday, and once that is completed the next one is on Friday (measured for a weekly rule on one weekday; for other rules this is expected, not measured). When the due date is not on the new rule's days the response adds recurrence_note; pass due_date to update_reminder to move it. The response reads back has_recurrence, reminder_recurrence_rules and due from the saved reminder after re-reading it (recurrence_read_back: false with recurrence_read_back_note when it cannot be re-read). interval must be 1 to 1000 and occurrence_count 1 to 10000 on every tool that takes recurrence: an interval below 1 or from 2^31 to 2^32, or an occurrence_count of 0, used to crash the server (measured), and the rest of the refused range is refused as unreasonable. Refused before anything is written: recurrence with clear_recurrence or with clear_due_date; a rule on a reminder that will have no due date; a rule on a completed reminder; and clear_due_date on a reminder that keeps repeating (a repeating reminder must have a due date; pass clear_recurrence with it to make it one-off). Undo restores the previous rule (tested in memory, and on a session MCP pending the release gate). How Reminders.app displays the off-rule occurrence was not checked.
Relative alarms on reminders (#333): create_reminder, each row of create_reminders_batch and update_reminder accept alarms_minutes_offsets, minutes before the due date (positive = before, negative = after; integers from -525600 to 525600, one year; the same bound now applies to the event tools), so the stored due date keeps its real time and the notification can come earlier (in the rows measured the list, and the one banner checked, showed the alarm time, see below). Only relative alarms are written: on update_reminder the list replaces the reminder's relative alarms and [] removes them, while absolute-date alarms (#227) and the location trigger (#229) are not changed. This differs from update_event, whose list replaces every alarm. A relative alarm needs a due date with a time: it is refused, with nothing written, when the reminder has no due date (the alarm would never fire) or a date-only one, because when Reminders fires a relative alarm on a day without a time has not been measured on a device (EventKit stores and reads it back; #333 step 0). On a recurring reminder EventKit is expected to move the alarm with each occurrence; that is not yet checked on a device (release gate). What Reminders.app shows (#433): in the 14 rows measured, the list row showed the earliest time-based alarm, relative or absolute, not the due time, so a reminder due 15:30 with [15] read 15:15 and with [-15] read 15:45. That is a fit to those rows, not a documented rule. The stored due date is unchanged (list_reminders reads 15:30). The one notification checked (#333: due 09:54, [2]) came early, and its banner showed the same time as the list row, 09:52, not the due time. No second banner was seen at the due time, but the first was still on screen, so one hidden behind it cannot be excluded. alarms_note says so when the earliest time-based alarm is not at the timed due time, on a call that passes alarms_minutes_offsets, due_date or realign_to_due. A call that touches none of them, such as a title change, gets no note, and neither does a date-only reminder, though #267 measured that the app goes on showing an absolute alarm's time there; so no note does not mean the list shows the due time. Measured list rows: [15], [60], [2], [15, 0], [0], [-15], absolute alarms at or before the due time, and [15] with an absolute alarm at the due time. Every other shape is inferred from them, for example [60, 15], [15, -15], [-15, -60], [1440], an absolute alarm after the due time, [-15] with an absolute alarm at the due time (no note), and [15] or [0] with an earlier one (note). They cannot decide [0, -15]: it gets no note for now, and release gate step 8 looks at it. The rows that showed the due time have no alarm before it, and an extra alarm at the due time did not bring it back ([15] with one read 15:15); firing was not checked on those 14 rows. An Early Reminder set in Reminders.app is different: the one made by hand read back with one absolute alarm at the due time and no alarm before it, so this server cannot write it. Keeping alarms_minutes_offsets is a default and can be revisited. The 14 rows were list rows of one iCloud list; the [60] and [2] rows came from an earlier disposable list (#333). Not checked: the detail panel, other devices, offsets that cross into another day ([1440]), when a [-15] alarm notifies, a past due date, a completed reminder, and whether update_reminder keeps an Early Reminder set in the app. The response lists the relative alarms read back as alarms_minutes_offsets (minutes before), with alarms_differ and alarms_note when they are not the ones asked for (when the display note applies too, the note says both). On a call with alarms_minutes_offsets (create_reminder, a batch row, update_reminder), if the reminder cannot be re-read after the save, or a create's store_differs lists alarm count, the response leaves alarms_minutes_offsets out and sets alarms_read_back: false with alarms_read_back_note. An update_reminder without alarms_minutes_offsets that changes the due date (due_date or clear_due_date) and leaves the saved reminder date-only or without a due date leaves its relative alarms in place and adds alarms_note: how many are left, that without a due date they never fire or that on a date-only reminder their firing has not been measured, and that alarms_minutes_offsets: [] removes them (after clear_due_date the count is taken from the saved object, not re-read; a due_date whose re-read failed gets no such note, and date_sync.aligned is false); a skipped duplicate create gets alarms_applied: false. Undo of the update restores the previous alarms, location alarm included. Tested in memory: the restore, and the #236 guard comparing alarms by value (it names alarms when one changed elsewhere); what a synced store reads back is pending the release gate.
Rows of create_reminders_batch are checked (#441): a row with any key other than title, notes, due_date, priority, calendar_name, calendar_source, tags and alarms_minutes_offsets fails, with nothing written for it, and the other rows go on. Such a key used to be ignored, so recurrence on a row made a reminder that does not repeat. recurrence and location_trigger need create_reminder.
Date-only reminders (#267): a due_date given as a bare date (2026-10-18) to create_reminder, create_reminders_batch or update_reminder makes a date-only reminder, a date with no time, as Reminders.app makes one; read back, its due.time is null. On update_reminder the start date is set to that day, also one set apart from the due date, and absolute-date alarms are removed, because Reminders.app displays the earliest one and would go on showing its time (checked on device); relative and location alarms are kept, and date_sync.absolute_alarms_removed counts what went. Giving a timed reminder its own date removes the time. A due date with a time works as before. A bare-date create_reminder (and each created row of create_reminders_batch) reads the saved reminder back and returns date_sync, as update_reminder does: date_sync.aligned is false when the due came back with a time, came back missing, or the reminder could not be re-read (#301). A written due that reads back missing also gives aligned: false on update_reminder, where aligned used to be left out. In list_reminders, a date-only reminder is overdue only once its day has ended in the host time zone, and in list_reminders and search_reminders its due_date / due_date_local read as 00:00 of that day in the host time zone (#297).
A reminder's own time zone (#241): list_reminders and search_reminders report it as item_timezone, a time zone identifier (usually IANA), or null when the reminder stores no time zone: a floating timed reminder, a date-only reminder, or one without a due date (a floating timed reminder is item_timezone null with due.time set). The per-reminder timezone is the host time zone, the zone of the *_local strings, not the reminder's.
Advanced Features (10) ✨ New in v0.3.0+
| Tool | Description |
|---|
search_events | Search events by keyword(s) with AND/OR matching |
list_events_quick | Quick shortcuts: today, tomorrow, this_week, next_7_days, etc. |
create_events_batch | Create multiple events at once (with per-event timezone) |
check_conflicts | Check for overlapping events in a time range |
copy_event | Copy an event to another calendar; delete_original moves it like move_events_batch (recurring events refused). undo of a plain copy deletes the copy, refused while the copy was changed since (#273) |
move_events_batch | Move events to another calendar in place, keeping recurrence and attendees; span / occurrence_dates for recurring events (#226) |
delete_events_batch | Delete events by IDs or date range, with dry-run preview (v1.0.0) |
find_duplicate_events | Find duplicate events across calendars (v0.5.0) |
create_reminders_batch | Create multiple reminders at once (v0.9.0); a row may carry store_differs and note, as create_reminder does (#261); a row whose save failed and could not be checked is kept and its error says how to check before creating it again (#289) |
delete_reminders_batch | Delete multiple reminders at once (v0.9.0); one undo recreates them (#243) |
Moving events (#226): a move reassigns the event's calendar, so recurrence, attendees and every other field are kept. The identifier stayed the same within an iCloud account; within a Google account it changed, and so does it across accounts, so read id_changed and new_event_id in each result (#435). When it changes, older undo records of that event follow it, and the undo of the move reports the new one. For a recurring event, span: this (default) moves only the occurrence named in occurrence_dates, which becomes a one-off; span: all moves the whole series; a recurring event without a date is refused. If an in-place move fails, the event is copied and the original removed, unless it has recurrence or attendees. Each result reports method (in_place / copied / split / unchanged) and any not_carried_over fields. Undo of an in-place move moves the event back; undo of a split or a copy restores the original in its calendar (a split occurrence as a one-off event; if its series (or one an undo recreated from it, matched by identifier, #321) already holds its original slot there, nothing is recreated and the copy is not looked up or removed; for an occurrence edited on its own, the copy is then the only version with that edit) and then removes the copy, but only when the copy is found under its identifier and unchanged since the move (#466). A copy changed since (in any field the #236 check compares, a change a sync makes on its own included), with attendees, not found (deleted, or given a new identifier), recorded without an identifier, not checkable, or whose removal failed is not removed, and the answer says so. It says the event is in both calendars only where the copy is known to be in the calendar it was moved to (its removal failed, it has attendees, or it changed in fields other than its calendar), and otherwise that it may be; removing the copy is up to the user. The restore of the original is never refused because of the copy.
Identifier after an update (#268): update_event and update_reminder answer with the identifier the item has after the save. It changes in four cases only: a calendar_name that moves the item to another calendar or list where the store gives it a new identifier (measured for events: a calendar in another account, #226, and between iCloud and Google for #484; another calendar within a Google account, #484; within an iCloud account the identifier stayed the same; Exchange was not run; a list of reminders in another account was not measured here; an edit of one occurrence with a new calendar is refused, since it would move the whole series), update_event with span: "future" from a later occurrence (the new series' identifier, also through the identifier of an occurrence edited on its own), span all or future with the identifier of an occurrence edited on its own that is the first occurrence left after the first was deleted (what remains gets a new identifier), and span all through the series' identifier when the series' first occurrence was edited on its own and still starts at its original time, or was deleted with the first occurrence left edited on its own (the call goes through that occurrence's identifier, and id changes when a new series starts there, #428). When a calendar change over the whole event (a one-off event, or a series with span all through its own identifier) gives it a new identifier, older undo entries of that event follow it (#484). The undo of such an update of a one-off event that is still one-off after it, with or without keep_later_edits, ends its answer with the new ID, as the undo of an in-place move does (#435); the undo of a series' calendar update is refused and its entry discarded, as for the updates of a recurring event that #263 does not restore, and so is the undo of a one-off event given a recurrence rule in the same call (read from the code, not measured). A split of the series is not followed, and neither is span future from the series' first occurrence with a calendar_name, which moved the whole series under a new identifier within a Google account: older entries keep the old identifier, and the undo of the series' creation answered not found there (#551). id_changed says whether it differs from the identifier you passed, and previous_id, present only when it changed, repeats that identifier. An edit of one occurrence (occurrence_date, span this) answers the series' identifier as id and adds occurrence_id, the identifier of that occurrence alone.
Writes through an occurrence's own identifier (#416): an occurrence edited on its own has its own identifier (on iCloud, the series identifier followed by /RID= and a number). What a span does through it depends on where the occurrence is:
- Span
this edits or deletes that occurrence. It takes no calendar_name that changes the calendar, recurrence or clear_recurrence: those are refused, as they reach the series. The same goes for a new calendar_name through the series' identifier with occurrence_date and span this (#426).
update_event with span all or future can write title, notes, location and recurrence through it (not recurrence with span all after the series' first occurrence was deleted). It can also write start_time, end_time, all_day: true, alarms, timezone, url and structured_location (#428), but only in the shapes measured on iCloud, all of these at once: a timed series repeating weekly, every week, on at most one day; one of these fields per call, or start_time with end_time, and nothing else in the call; start_time and end_time only as a new time of day, the start and the end staying on their dates; the occurrence still at its original start and differing from an unedited occurrence only in title, notes, location or alarms; alarms only while it has the series' alarms; and timezone, url and structured_location only in a series that ends after a number of occurrences, whose first occurrence is still there and which has no other occurrence edited on its own; with span future every one of these fields needs that series. On a series that has started, these writes take the started-series rules (#451), through the occurrence's own identifier and through the series' identifier alike (measured on iCloud after #471 and #478); a timezone from an occurrence that has happened is refused by #478's check. all_day: true from the first occurrence left, after the first was deleted, is refused. After a date was written through it, its /RID= stays at the old slot (measured), so later dates through it are refused. all_day: true only with span all, while the series' first occurrence is still there (with span future #451 refuses it, and so does this check). all_day: true has no way back through it: all_day: false is refused, and so are dates on an all-day series. Anything else is refused and nothing is written, even a field that changes nothing, such as all_day: false. For the rest, use span this or the series' identifier, as below.
update_event span future updates from that occurrence on. From a later occurrence it ends the series there and starts a new one, which can resend invitations; id_changed reports it.
update_event span all updates every occurrence when it is the first one left. With an earlier occurrence left it would split the series, so it is refused and writes nothing: use the id that list_events shows for the occurrence that comes first in the series, by its original date. A series whose first occurrence was deleted has no whole-series update unless its first occurrence left was edited on its own (#326); what remains is span future from a later occurrence, or span this on each.
- A value the occurrence already holds is refused with both spans: it reaches no other occurrence, though the call would answer
updated (measured). Leave the field out, or use the series' identifier.
- A write that starts a new series (span
future from a later occurrence, or either span from the first one left after the first was deleted) is refused while the occurrence holds its own location, alarms, time zone, all-day flag, availability or coordinates, because the new series took its location and alarms (measured). Writing location replaces a location given as text.
days_of_week in a new recurrence is checked against the occurrence's original day, so from an occurrence moved to another weekday a rule on the day it shows is refused. With span future from a later occurrence, occurrence_count is refused, through the series' identifier too, because the store counts from the original first start (count 6 from the third occurrence gave 4, #443); use end_date.
- The series' identifier is the
id that list_events shows for an occurrence that was not edited on its own. With span all it took the other fields, with an edited occurrence in the series. Occurrences edited on their own keep what was edited, so use span this on them afterwards. clear_recurrence there leaves one event at the series' first date, without the edited occurrences. all_day changing the flag there (or with span future from the first occurrence) is refused while the series has an edited occurrence, since it brought that occurrence's original slot back as an extra occurrence; it is also refused when such an occurrence cannot be ruled out, because the scan cannot show where the series ends (no end, an end past about five years from its start, or a count whose last occurrence cannot be worked out) or cannot list it, and it goes ahead when the same call clears the rule (#442); on a series whose rule has an end date, a change this lets through is then refused by #509, since the series is all-day before or after the write, unless the same call clears the rule or passes a recurrence with occurrence_count or no end; clear_timezone is refused on a series with a count, as it dropped the last occurrence, with or without an edited occurrence (#455), and a calendar of another account was not run. For a calendar of the same account, move_events_batch span all moves the whole series. For span future, use span this on this occurrence, then that id with the next occurrence's occurrence_date and span future; that leaves out all_day, clear_recurrence and calendar_name, which do not stay within the later occurrences (#451), and clear_timezone, which was not run.
- The series' identifier with the first occurrence edited (#428): when the first occurrence was edited on its own and still starts at its original time, or was deleted and the first one left was edited on its own, the series has no object to save.
update_event and delete_event with span all through the series' identifier then go through that occurrence's own identifier, under the rules above, while that occurrence does not start after the next occurrence's slot or another occurrence's shown start. When it does, its own identifier takes no span all or future write and no span future delete either: that save was not measured. After a deleted first occurrence a new recurrence with span all is refused, through the series' identifier or that occurrence's own: it would start a new series from a later slot, which was not measured with a rule. id stays the series' identifier unless a new series starts, and occurrence_id names the occurrence. The delete removes every occurrence (measured on iCloud with series of 5, open-ended series and further edited occurrences, listed over seven years afterwards); its response adds occurrence_id and undo_note, as it cannot be undone. Span future through the series' identifier is still refused in that shape; the first occurrence's own id takes delete_event span future. delete_events_batch with span all, by event_ids or by date range, deletes the series' row through that occurrence too, and its dry run says so (#436, #427). That delete cannot be undone: the dry-run row gives occurrence_id and an undo_note; the real call lists it under through_first_occurrence with an undo_note and leaves it out of the call's undo, which restores the other rows, or, when no other row was deleted, is refused and dropped as delete_event's is.
- Calls these refusals took away (#416):
start_time alone with span all or future from an occurrence moved by a time, keeping the series' length, did what it says. It stays refused, because that occurrence has a time of its own; use the series' identifier. Dates on the only occurrence left are always refused, as there is no unedited occurrence to compare it with, and so are dates when every remaining occurrence was edited on its own; span this does the same there.
- With span
this or future, occurrence_date must be that occurrence's day, or the call is refused: it was ignored, and the write started at the occurrence the identifier names.
delete_event span future deletes that occurrence and the later ones, so from the first occurrence it deletes the whole series.
delete_event span all deletes that occurrence only, so it is refused and deletes nothing while another occurrence remains. To delete the whole series, use the id of the occurrence that comes first in the series: with span all when it has no /RID= part, with span future when it has one (that delete cannot be undone). A series that may reach past the scan, about five years, counts as having other occurrences. delete_events_batch by event_ids refuses that row, in the dry run too, and goes on with the others; occurrences named in the same call do not count as remaining, and with span all their rows run first, in the dry run too. By date range, with span all, the row is refused the same way while another occurrence of its series is not listed, in the dry run too, which does not count it in deletions (#427). When the series' own identifier is listed too and its row deletes on its own, an occurrence whose id has a /RID= part is left to that row, which deletes the series with it, also for a series that may reach past the scan; otherwise the occurrence's row runs first, as by event_ids, and the series' row then reaches the rest.
move_events_batch span all moved the whole series and kept the identifier, within one iCloud account, and undo moved it back; across accounts was not measured. Span this needs that occurrence's own day in occurrence_dates, and copies it to the target as a single event, removing it from the series; without a date, or with another day, it is refused and nothing moves (#426). copy_event with delete_original refuses such an identifier, as it does a recurring event.
This was measured on iCloud. The whole-series update and delete above go through the occurrence that comes first, which the series' identifier reaches too in those shapes (#428). On Google, #320 measured /RID= and isDetached as reliable, but these refusals did not run there. A source with no /RID=, which Exchange may be (not measured), cannot list the rest of the series from the identifier, so span all, and update_event span future, are refused there, also for a single event it wrongly reports as an edited occurrence; use span this. On iCloud an occurrence past the scan, in a series that reaches more than about five years from its start, is refused the same way, and the series' identifier takes the whole-series update and delete (measured on a series started about seven years ago).
The series' identifier with the day of an edited occurrence (#532): update_event, delete_event (span this or future with occurrence_date) and move_events_batch (span this with an occurrence date) look an occurrence up by the series' identifier and the day it starts on. An occurrence edited on its own has an identifier of its own, so that lookup does not find it, and these calls answered Event not found for a day on which the calendar shows an occurrence. An occurrence that was not edited on its own and starts on the day is resolved and written to as before. Only when that lookup finds nothing does the call look, among the events of that day, for occurrences of that series that were edited on their own and start on that day. With one found, the call is refused and writes nothing; the refusal says that an occurrence of this series that starts on that day was edited on its own, so the series' identifier and that day do not address it, and gives its identifier, the one list_events shows:
- span
this (update_event, delete_event): pass that identifier as event_id and leave occurrence_date out.
update_event with span future: through that identifier a span future call takes only some fields (the #416 list above) and answers which; for the rest the refusal names span this on that occurrence, and for the later ones the next occurrence that was not edited on its own with span future, and ends with the limit of that way: it leaves out all_day, clear_recurrence, calendar_name and clear_timezone, and if that identifier is refused too the shape has no tested way. A span future call through that identifier starts at the occurrence's original date, not at the day it starts on now, and this server does not read that date. So the refusal says both directions without a date: when that date is before the day asked for, occurrences before that day are written too; when it is after, the occurrences between that day and it are not reached (measured on iCloud with a title, through an occurrence moved later and one moved earlier, and through one moved later in a series with no time zone).
delete_event with span future: a delete through that identifier starts at the occurrence's original date, which this server does not read, and cannot be undone. The refusal says both directions in the same way: occurrences before the day asked for are deleted too when that date is earlier, and the occurrences between that day and that date are not reached when it is later (both measured on iCloud). In a timed series with no time zone it also names a known defect (#549, measured on iCloud): that delete removes the later occurrences of the series, answers deleted, and leaves the edited occurrence itself.
- Every span
future refusal also says, whatever the occurrence, what #550 measured on iCloud: where the store recorded an edited occurrence at another time of day than the series (a series that got its time zone after its occurrences were edited), a span future update through its identifier moved the later occurrences of the series to another day, and span this on that occurrence is the tested way; a span future delete through it removed that occurrence and the later ones, and an occurrence the rule shows on its day stayed. This server does not read where the store recorded an occurrence, so the sentence is given every time.
- a
move_events_batch row: pass that identifier in event_ids with the day the occurrence starts as its occurrence_dates entry. That entry is read in the occurrence's own time zone, so for an occurrence that was given a zone of its own the day can differ from the day in the series' zone; the refusal prints the day to pass. On iCloud an edited occurrence read back the series' zone, or the zone it was given, whatever time zone the writing and the reading process ran in, and the printed day was accepted each time; on a Google calendar the zone such an occurrence reports differed between runs (#548, cause not separated), and this refusal was not run there. The other rows of the call go on.
With two or more that start on the day (one edited in place, one moved onto it), all are listed and none is picked; a move_events_batch row then prints their starts in the series' zone, while the follow-up call reads the day in each occurrence's own zone. An occurrence that still starts on the day under the series' identifier is found as before, also when an edited one was moved onto the same day. The identifier is written into the text only when it is exactly the series' identifier that was passed, followed by /RID= and digits (the shape read on iCloud), made of ASCII letters, digits and : / = - . _ @, and at most 200 characters long; otherwise the text says to use the id list_events shows. The digits are not read as a date: no refusal prints or implies the original date of an occurrence.
When no edited occurrence starts on the day, the answer is not found as before, and its text now gives the day as a date in the event's time zone (this Mac's for an event with none), Event not found: … (no occurrence on 2026-12-21), where it printed a UTC instant (#535); a move_events_batch row still answers No occurrence of this event falls on occurrence_date. Two cases answer not found although the calendar has the occurrence: an occurrence edited on its own and moved to another day, asked for by the day it was moved off (the search reads the day an occurrence starts on, not the slot the rule gave it; list_events shows the occurrence under its own identifier, and reading that slot is #539's), and an edited occurrence whose identifier is not the series' identifier followed by /RID= (no such source was measured). Measured on iCloud only: Google and Exchange were not run for this change (through EventKit, Google gives an edited occurrence an identifier of the same shape, #320).
All-day dates with an offset (#372): all-day dates are whole days read in this Mac's time zone. A start_time or end_time written with another offset is converted first and can land on another day (2027-04-11T23:59:59+07:00 on a +08:00 Mac is 04-12, so the event gets one more day). The event is still saved that way; create_event, each create_events_batch result and update_event (when the event is all-day after the call, for the dates it gave) add a warnings list whose entries name the field, its day in the written offset (written_day), the day in this Mac's zone the request's dates are written with (host_day; a skipped duplicate writes nothing, and its message says the existing event was not changed) and a message. The comparison is on the days, so an offset whose day agrees, or a value without an offset, gives no warning. Send all-day dates without an offset.
Alarms on a Google calendar (#317): measured on a calendar hosted by Google. About a minute after the save, an absolute alarm reads back as a relative alarm at the same time, and a location alarm that copy_event, or the undo of delete_event on a one-off event, writes becomes a plain alarm at the event's start; the response cannot see either. Relative alarms were kept on every path, including alarms_minutes_offsets written by update_event on a one-off event. Google never listed an email alarm, on any event measured, nor the location alarm of the event that was not copied, though this Mac still reads both; reading an event back shows this Mac's view only, so it cannot show what Google holds. The absolute-alarm change and the email alarm held for an event this server did not write too. Not measured: Exchange and other accounts, copy_event with delete_original, the fallback copy and cross-account move of move_events_batch, create_events_batch, the undo of a series, an occurrence or a batch, sound alarms.
Undo/Redo (3) ✨ New in v1.4.0
| Tool | Description |
|---|
undo | Undo the most recent recorded calendar/reminder operation. create_calendar, update_calendar and delete_calendar are recorded only so that undo does not revert an older operation in their place: their undo is refused and the entry discarded, and the next undo reverts the operation recorded before it (#273) |
redo | Redo the last undone operation. Only completions are written again; for a create, delete, update or move, redo writes nothing, answers success: false with the tool to use, and drops that entry from the redo history (#247). Not replaying those writes is the design (#295): the tool that made them repeats them |
undo_history | List undoable operations with timestamps |
Undo does not overwrite a change a person made since (#236): an undo of a create, update, move or completion first re-reads the event or reminder and checks that nothing the undo would overwrite or delete was changed since that operation (for a move, the calendar; for a recurring event created here, also occurrences edited on their own, looked for up to four years from the first occurrence; an occurrence counts when it differs from the series in any compared field, alarms, time zone, place and availability included, and one back at the series' values does not; availability counts only when both the occurrence and the series report one, so on a store that reports it on one side only an occurrence's own availability is not seen). A field already changed back to the value the undo writes does not count. Two changes a calendar app or server makes on its own are not treated as edits, so they never block an undo and an update-undo overwrites them: an alarm sound, and coordinates added to a place that had none. If something was changed, nothing is written, the error names the changed fields, and the entry stays in undo_history; whoever made the change should decide whether to change it back and undo again, or to give up that undo with undo + discard_id. Three create-undo refusals leave only the choice whether to discard: occurrences edited on their own, which cannot be put back into the series; a series whose occurrences could not be checked (unchecked_occurrences), which cannot be checked later either; and a series whose rule was shortened (recurrence; an update or delete of an occurrence and the following ones does this), whose cut-off part cannot be put back. Redo of a completion makes the same check against the state the undo left. An update_event that touched a recurring event (one occurrence, span "future" or "all", or rules added or removed) cannot be undone: undo on it writes nothing, says to revert the change in Calendar if it should be reverted, and drops that entry so earlier ones stay undoable (#262: such an undo used to delete the rest of a series). The undo of an earlier update or move of a one-off event is refused the same way if the event repeats or is an edited occurrence by the time of the undo (a move of an already edited occurrence included), so update-undo and one-off move-undo never write to a recurring event (a series move-undo still moves the whole series back, by design), with the one exception below.
Undoing a whole-series update on iCloud (#263): one recurring update is restored, an update_event that passed only event_id, span and title, notes or location, with span all through the series' own identifier, on an iCloud calendar, on a series that starts and ends within the dates undo lists its occurrences over (at most four years; never a series with no end, nor a count whose last occurrence cannot be bounded, which is a count with days of the month, months, weeks or days of the year, set positions, days of the week on a daily, monthly or yearly rule, or a monthly or yearly start after the 28th) and whose first occurrence was not edited or deleted on its own (through the series' identifier such a series goes through an occurrence's own identifier, #428, or a stand-in, #326, or shows a first occurrence that is not its first slot), with no location written over a place with coordinates (the series' own or that of an occurrence edited on its own) or over a series place named other than its location, with the same occurrences edited or deleted on their own listed before and after the save, and where each occurrence edited on its own, in each field it wrote, either followed the update (it had the series' old value and took the new one) or kept an own value different from both, and nothing else of it changed. The two shapes are inferred across the three fields from what was measured (follows: notes and location; keeps: title), so an occurrence that already held the written value is in neither, unless the written value equals the old one; the inverse was measured only on a series that had not started. An occurrence edited on its own and moved more than a year outside the listed dates is not listed: its slot counts as deleted, and it is not checked or compared. This record's own comparisons read nil and empty notes, location and place title as the same, and a place without coordinates whose title is the location string moves with the location; #236's guard on the series compares them exactly, so the undo of a write that clears a field may be refused there. As for every update-undo, coordinates added later to a place that had none do not block the undo and are overwritten. Any other update that touched a recurring event stays refused and discarded as before.
undo_history lists such an update as Updated recurring event: <title> (whole series; undo restores its <fields>). A refresh is requested before each of the three listings (before the save, after it, at undo); it runs in the background, so a listing is not proven current. The undo writes only when, read again, the series has the same identifier and rule, is still on iCloud, holds the values the update left (#236), and has exactly the occurrences edited or deleted on their own it had after the update; otherwise nothing is written and the entry is kept, to be given up with discard_id once the user agrees. It writes the old values in one save and reads the series back: if the fields, the rule or those occurrences do not match the state before the update, the error says what differs and the entry is discarded. Not restored: span "this" or "future", a rule added, removed or changed, any other field (time, all-day, time zone, calendar, alarms, URL, place), and every account that is not iCloud. iCloud is told by its account: a CalDAV account titled "iCloud" (or the legacy iCloud type); another CalDAV account with exactly that title would pass. The undo itself is checked by the release gate on the session MCP before the tag.
Keeping later edits when undoing an update (#265): when the undo of an update_event on a one-off event, or of an update_reminder, is refused because the item changed after the update, the error now lists the fields the update changed and the fields changed after it separately. When none of the later edits is in what the update changed, it says so; undo with keep_later_edits: true (ask the user first) then restores only the fields the update changed and keeps the later edits, and its answer names both. Fields that move together count as one: an event's start, end, all-day flag, time zone, alarms, calendar and availability (a relative alarm means another time once the event turns all-day or timed, and the calendar decides which alarms and availability it keeps); its location and place (coordinates the update added count as its change); a reminder's due date, start date, alarms, repetition, completion and list. An update that changed none of the fields undo restores is not offered the merge. A later edit inside what the update changed refuses as before, and so does any field outside these groups. Without the flag nothing changes: undo restores every recorded field and refuses on any later edit. Any other undo runs as without it, an update that touched a recurring event stays refused or, for #263's whole-series update, undoes as without the flag, and the flag cannot be combined with discard_id or restore_available. Only unit tests and source pins cover the merge; the write was not run on a device (undo is stateful, so it waits for the release gate on the session MCP).
A series whose first occurrence was deleted (#326, #335): its id still works. The tools reach it through its earliest remaining occurrence, looked for from a day before the series' first start up to 1460 days on, in the series' calendar: a move, a copy, a delete and an update of a single occurrence (occurrence_date, span this) work, and undo of those moves and deletes restores the series. A whole-series update, or a delete or update from a date on, is refused with an explanation when an occurrence edited on its own comes before the remaining ones. If every remaining occurrence starts more than 1460 days after the series' first start, none is found and the id answers Event not found: that cannot be told apart from a series with nothing left without a wider search, so change such a series in Calendar.
Undo of deleted occurrences and availability (#244, #245): undo of a delete_event that removed one occurrence of a recurring event (span "this") brings that occurrence back as a one-off event at its time, not into its series (EventKit cannot put it back), and an absolute-date alarm of the series becomes an alarm at its start (the undo text names it, once for a batch). Undo of a span "future" delete recreates the series only when the delete started at the series' first occurrence and removed all of it; otherwise (part of the series is left, the delete started at the last occurrence, or the id named an edited occurrence) it writes nothing, says to restore the occurrences in Calendar, and drops that entry. A delete_events_batch holding such a delete is refused before any of its events is restored. Undo of a whole-series delete (that span "future" case, or span "all") recreates the series from its rules and then restores its exceptions inside the checked window (at most four years: from three years before the delete, or from one day before the first occurrence when that is later, moved earlier for a rule that ends sooner, a count of occurrences included, so a series that began long ago is checked around the time of the delete and one begun within about three years keeps the window from its first occurrence, #319): an occurrence deleted on its own earlier stays deleted, and one edited on its own comes back as a separate one-off event that no longer belongs to the series (#285); the undo text says how many of each. Occurrences are listed a year beyond each window edge and judged by their rule slot, so an edited occurrence moved out of the window still comes back as a one-off (one moved more than a year past it is not restored and its slot counts as deleted; if the record does not match the recreated series, no exception is applied and the text says so). The series' first occurrence is never removed: if it was edited or deleted on its own it is kept from the rule and the text says so. Exceptions outside that window, and those of a series that could not be listed when it was deleted, come back from the rules alone, which the text also says. Undoing the earlier delete of an occurrence that the restored series already holds writes nothing and says so; the occurrence is matched by the series it belonged to (or the series an undo recreated from it) and the slot the rule gave it, not by title (#321), so an unrelated series with the same title at that time does not stop it from coming back, and a record that cannot say its series writes the occurrence and says so. The same check covers an occurrence edited on its own that was deleted by its own id beside its series. undo_history lists such a record as Deleted event: <title> (undo recreates the series and its exceptions within the checked window (from <start> up to <end>): …) (or … within the checked windows (from … up to …, and from … up to …): …) for a count whose window around the delete starts after its first occurrence) and a delete_events_batch record holding one as Batch (<N> operations; undo recreates <K> series and their exceptions within the checked window or windows: …) (a batch whose undo is refused says undo not available instead). Checked on iCloud with delete_event (span "future") and delete_events_batch (span "all"). Delete-undo now keeps an event's availability (free, busy…) where its calendar supports the value, and the create and update checks above compare it.
Batch deletes undo as one entry (#185, #243, #248): delete_events_batch, a series delete, delete_reminders_batch and cleanup_completed_reminders each record one undo entry holding the items the call actually removed, and it becomes the newest entry. One undo recreates them one save at a time within that single call (a cleanup holds up to its limit, 1000 by default, or every reminder_ids entry), each under a new identifier and with what the undo snapshot records; a reminder's subtasks are not recorded. Before the first write, the calendar or list each item goes back into is checked, by its recorded identifier as the restore looks it up (a same-named list in another account does not count); if one is missing or read-only (read again after a refresh is requested), nothing is written, the entry stays whole, and the error says how many items have their calendar or list in place; giving up with discard_id drops them all. With restore_available: true (ask the user first, #287), undo instead restores the items whose calendar or list is in place and keeps an entry of only the others, under the same id; the answer is success: true with partial: true and kept, says which kinds of calendar or list stop the kept items (naming the items, not the calendar, list or account), and a later undo restores them once their calendar or list is back, while discard_id then drops only them. When no item can be restored the refusal stands, and the argument changes nothing for any other undo. If a save still fails, the entry keeps only the items not yet restored, under the same id, with the failing one moved to run last, so the next undo restores the others first, unless the failing one's calendar or list is by then missing or read-only, which the check above refuses. Each such call clears the redo history, and only the newest 50 undo entries are kept.
Batch delete by event_ids with span this or future (#452): the rows run in the given order, and the dry run runs them the same way, with one exception below. An id repeated after a row that deleted it, or after a row the earlier delete took, fails with Event not found: an earlier row of this call deleted it, in the dry run too. With span future the id of an occurrence edited on its own (it contains /RID=<slot>) deletes that occurrence and the later occurrences of its series. Its dry-run row says so with also_deletes_later_occurrences: true and an undo_note, and the real call lists it under following_occurrences_deleted with an undo_note: such a delete cannot be undone and makes the call's undo refuse and drop its record, so none of the call's rows comes back. Every row is looked up first. The exception: the id of a later occurrence of that series that resolves and that the earlier delete reaches is shown in the dry run as covered_by_earlier_row: true, with its dates, and counted in covered_by_earlier_rows, not in already_removed, because the dry run cannot see that delete. The real call counts it in already_removed when its lookup no longer finds it, taken as removed with the series (iCloud removed it, 2026-11-09), or, when the store kept it, deletes it as a row of its own; that row is then listed under following_occurrences_deleted too, which its dry-run row does not show. So, when no row of the real call fails for another reason (a lookup that raises is one), the dry run's rows without an error equal the real call's succeeded plus already_removed. This was checked for occurrences edited in place; a deleting occurrence moved before a later row's shown start was not. A /RID= slot before 2001 is a negative number, which is not read, so such a delete covers no later row: that row is looked up and, when it is gone, fails as not found. An occurrence id that never resolved, or that resolves to an event with rules, fails in both. A bare recurring id needs an occurrence date and fails in both; after a row deleted its series from the first occurrence, the dry run refuses it and the real call does not find it. Measured on iCloud with --cli (2026-11-09): a repeated one-off, two occurrences' own ids of a weekly series in either order and from the first occurrence, and an occurrence's own id that never existed; other sources were not measured. also_deletes_later_occurrences, following_occurrences_deleted and their undo_notes are read from /RID= in the id, an iCloud form (#416), while the undo refusal follows the store's isDetached.
Installation
The quick paths live at the top of this README. This is the full reference — manual config, source builds, permission edge cases, in-place upgrades, and CLI mode.
Requirements
- macOS 14.0+ (Sonoma or later — required since v1.11.0 for the full TCC permission API)
- Xcode Command Line Tools (only if building from source)
Claude Desktop
One-click (recommended): download the latest che-ical-mcp-<version>.mcpb from Releases, double-click, and restart Claude Desktop.
Manual config: download the binary, then point claude_desktop_config.json at it.
curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o /usr/local/bin/che-ical-mcp
chmod +x /usr/local/bin/che-ical-mcp
Edit ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop:
{
"mcpServers": {
"che-ical-mcp": {
"command": "/usr/local/bin/che-ical-mcp"
}
}
}
Claude Code — plugin (recommended)
claude plugin marketplace add PsychQuant/che-ical-mcp
claude plugin install che-ical-mcp@che-ical-mcp
- Inside Claude Code, the slash equivalents
/plugin marketplace add PsychQuant/che-ical-mcp and /plugin install che-ical-mcp@che-ical-mcp work the same way.
- Add the marketplace through its Git repo (
owner/repo), not a raw marketplace.json URL — the plugin source is a same-repo relative path (./plugin) that only resolves when added via Git.
- Also bundled in the
psychquant-claude-plugins aggregator (claude plugin install che-ical-mcp@psychquant-claude-plugins); both serve the same versioned binary.
- The wrapper auto-downloads the binary to
~/bin/CheICalMCP on first use if it isn't already there.
Claude Code — standalone MCP
mkdir -p ~/bin
rm -f ~/bin/CheICalMCP
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
💡 Tip: Keep the binary in a local directory like ~/bin/. Cloud-synced folders (Dropbox, iCloud, OneDrive) can trigger MCP connection timeouts when sync touches the file.
Build from Source (optional)
git clone https://github.com/PsychQuant/che-ical-mcp.git
cd che-ical-mcp
make release && make install
claude mcp add --scope user --transport stdio che-ical-mcp -- ~/bin/CheICalMCP
⚠️ Swift 6 / Xcode 18 users: Don't run swift build directly — the upstream MCP SDK has a concurrency error (swift-sdk#214). The Makefile auto-detects this and falls back to Swift 5 language mode.
Grant Permissions
On first use, macOS will prompt for Calendar and Reminders access. Click Allow for both.
⚠️ macOS Sequoia (15.x) Note: The permission dialog is attributed to the parent application that launched the MCP server, not the binary itself. This means:
| Environment | Permission Attributed To |
|---|
| Claude Desktop | Claude Desktop.app ✅ (works automatically) |
| Claude Code in Terminal.app | Terminal.app ✅ (works automatically) |
| Claude Code in VS Code | VS Code ❌ (may not show dialog) |
| Claude Code in iTerm2 | iTerm2 ✅ (works automatically) |
If the permission dialog doesn't appear (common with VS Code), you need to add NSCalendarsFullAccessUsageDescription to VS Code's Info.plist:
/usr/libexec/PlistBuddy -c "Add :NSCalendarsFullAccessUsageDescription string 'VS Code needs calendar access for MCP extensions.'" \
"/Applications/Visual Studio Code.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :NSRemindersFullAccessUsageDescription string 'VS Code needs reminders access for MCP extensions.'" \
"/Applications/Visual Studio Code.app/Contents/Info.plist"
codesign -s - -f --deep "/Applications/Visual Studio Code.app"
Note: This modification will be overwritten when VS Code updates. You'll need to re-apply it after each VS Code update.
Upgrading an existing install
The plugin wrapper auto-downloads on fresh installs but does not replace an existing binary. To upgrade in place:
~/bin/CheICalMCP --self-update
This queries GitHub Releases for the latest tag, downloads the new binary, checks it against the published SHA-256, the maintainer's Developer ID signature and Apple notarization, and only then atomically replaces the current one (any failed check leaves your install untouched). If it is running as an MCP server, restart your MCP host (Claude Desktop / Claude Code) afterward to pick up the new version. Manual fallback: rm -f ~/bin/CheICalMCP && curl -L https://github.com/PsychQuant/che-ical-mcp/releases/latest/download/CheICalMCP -o ~/bin/CheICalMCP && chmod +x ~/bin/CheICalMCP.
CLI Mode (no MCP server)
All 29 tools can be invoked directly from the command line, no MCP server required:
CheICalMCP --cli list_events --start_date 2026-03-29 --end_date 2026-03-30
echo '{"tool":"list_calendars","arguments":{}}' | CheICalMCP --cli
claude -p "Run: ~/bin/CheICalMCP --cli list_events_quick --range today"
Handy for launchd jobs, shell scripts, CI pipelines, and agents that prefer a subprocess over the MCP protocol. TCC permissions still apply — run CheICalMCP --setup first if needed: from v1.23.0 a context without a Calendar and Reminders grant of its own uses the grant --setup creates (#343).
v1.0.0 Features
Flexible Date Parsing
All date parameters now accept 4 formats:
| Format | Example | Interpretation |
|---|
| Full ISO8601 | "2026-02-06T14:00:00+08:00" | Exact date and time (offset preserved) |
| Without timezone | "2026-02-06T14:00:00" | Uses event timezone if provided, otherwise system timezone |
| Date only | "2026-02-06" | Midnight in event timezone or system timezone; for a reminder due_date, a date-only reminder with no time (#267, see "Date-only reminders") |
| Time only | "14:00" | Today at that time |
Per-Event Timezone (v1.5.0)
Set the display timezone for individual events — essential for multi-timezone travel itineraries.
"Create a flight departure at 09:14 Berlin time"
→ create_event(title: "Flight LH123", start_time: "2026-04-08T09:14:00", timezone: "Europe/Berlin", ...)
"Update the hotel check-in to Dubai time"
→ update_event(event_id: "...", timezone: "Asia/Dubai")
"Remove the custom timezone from an event"
→ update_event(event_id: "...", clear_timezone: true)
timezone parameter accepts IANA identifiers (e.g., Europe/Berlin, America/New_York, Asia/Taipei)
- When
timezone is provided, naive datetimes (without offset) are interpreted in that timezone
- except
update_event's occurrence_date, which names an occurrence of the event as it is now: without an offset it is read in the event's current time zone, as on delete_event and move_events_batch (#383, #270)
- with an offset it is used as given, and its day is taken in the event's current time zone; the response's
occurrence_start gives the start of the occurrence it matched
- Event output includes the event's own timezone in
timezone field and formats start_date_local/end_date_local accordingly
- Event output also reports
item_timezone (#386): the event's own time zone identifier (usually IANA), or null when the event stores no time zone (a floating event; all-day events are floating). timezone falls back to the host time zone for those, so item_timezone is what tells them apart from an event stored in the host zone. With display_timezone, the *_local strings are in that zone; neither field changes
- Available on
create_event, update_event, and create_events_batch
- Undo/redo preserves per-event timezone
Alarms (Read)
Event responses list the event's time-based alarms as alarms (#240), in the shape the reminder read tools use (#231), so a caller can check what alarms_minutes_offsets wrote and see absolute-date alarms. Available in list_events, search_events and list_events_quick (all three outside detail_level: summary; fields: ["alarms"] selects it), and in check_conflicts.
{"kind": "relative", "minutes_before": 15}: measured from the start, positive = before, negative = after (the sense of alarms_minutes_offsets)
{"kind": "absolute", "absolute_date": "...Z", "absolute_date_local": "..."}: absolute_date_local is in the zone of the other *_local strings (display_timezone when given)
- Absolute alarms come first by date, then relative alarms earliest first;
[] when none. Location alarms are not listed. An occurrence reports the series' alarms unless it was edited on its own (then its own), as EventKit returns them
Attendees & Organizer (Read-Only)
Event responses include participant information when available. These fields are read-only due to EventKit limitations — they cannot be set or modified through the MCP.
Available in: list_events, search_events, list_events_quick, check_conflicts
attendees (array, optional) — Present when the event has participants. Each attendee object contains:
| Field | Type | Description |
|---|
name | string or null | Display name, null if not in Address Book |
email | string | Email address extracted from participant URL |
role | string | One of: unknown, required, optional, chair, non_participant |
status | string | One of: unknown, pending, accepted, declined, tentative, delegated, `com |