MCP Server Apple Reminders

1# Apple Events MCP Server ![Version 1.3.0](https://img.shields.io/badge/version-1.3.0-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green)
2 
3[![X Follow](https://img.shields.io/twitter/follow/FradSer?style=social)](https://x.com/FradSer)
4 
5English | [简体中文](README.zh-CN.md)
6 
7A Model Context Protocol (MCP) server that provides native integration with Apple Reminders and Calendar on macOS. This server allows you to interact with Apple Reminders and Calendar Events through a standardized interface with comprehensive management capabilities.
8 
9## Features
10 
11### Core Functionality
12 
13- **List Management**: View all reminders and reminder lists with advanced filtering options
14- **Reminder Operations**: Full CRUD operations (Create, Read, Update, Delete) for reminders across lists
15- **Rich Content Support**: Complete support for titles, notes, due dates, URLs, and completion status
16- **Native macOS Integration**: Direct integration with Apple Reminders using EventKit framework
17 
18### Enhanced Reminder Features (v1.3.0)
19 
20- **Priority Support**: Set reminder priority (high/medium/low/none) with visual indicators
21- **Recurring Reminders**: Create repeating reminders with flexible recurrence rules (daily, weekly, monthly, yearly)
22- **Location-Based Triggers**: Set geofence reminders that trigger when arriving at or leaving a location
23- **Tags/Labels**: Organize reminders with custom tags for cross-list categorization and filtering
24- **Subtasks/Checklists**: Add checklist items to reminders with progress tracking
25 
26### Advanced Features
27 
28- **Smart Organization**: Automatic categorization and intelligent filtering by priority, due date, category, or completion status
29- **Powerful Search**: Multi-criteria filtering including completion status, due date ranges, tags, and full-text search
30- **Batch Operations**: Efficient handling of multiple reminders with optimized data access patterns
31- **Permission Management**: Automatic validation and request for required macOS system permissions
32- **Flexible Date Handling**: Support for multiple date formats (YYYY-MM-DD, ISO 8601) with timezone awareness
33- **Unicode Support**: Full international character support with comprehensive input validation
34 
35### Technical Excellence
36 
37- **Clean Architecture**: 4-layer architecture following Clean Architecture principles with dependency injection
38- **Type Safety**: Complete TypeScript coverage with Zod schema validation for runtime type checking
39- **High Performance**: Swift-compiled binaries for performance-critical Apple Reminders operations
40- **Robust Error Handling**: Consistent error responses with detailed diagnostic information
41- **Repository Pattern**: Data access abstraction with standardized CRUD operations
42- **Functional Programming**: Pure functions with immutable data structures where appropriate
43 
44## Prerequisites
45 
46- **Node.js 18 or later**
47- **macOS** (required for Apple Reminders integration)
48- **Xcode Command Line Tools** (required for compiling Swift code)
49- **pnpm** (recommended for package management)
50 
51## macOS Permission Requirements (Sonoma 14+ / Sequoia 15)
52 
53Apple now separates Reminders and Calendar permissions into _write-only_ and _full-access_ scopes. The Swift bridge declares the following privacy keys so Claude can both read and write data when you approve access:
54 
55- `NSRemindersUsageDescription`
56- `NSRemindersFullAccessUsageDescription`
57- `NSRemindersWriteOnlyAccessUsageDescription`
58- `NSCalendarsUsageDescription`
59- `NSCalendarsFullAccessUsageDescription`
60- `NSCalendarsWriteOnlyAccessUsageDescription`
61 
62When the CLI detects a `notDetermined` authorization status it calls `requestFullAccessToReminders` / `requestFullAccessToEvents`, which in turn triggers macOS to show the correct prompt. If the OS ever loses track of permissions, rerun `./check-permissions.sh` to re-open the dialogs.
63 
64If a Claude tool call still encounters a permission failure, the Node.js layer automatically runs a minimal AppleScript (`osascript -e 'tell application "Reminders" …'`) to surface the dialog and then retries the Swift CLI once.
65 
66### Troubleshooting Calendar Read Errors
67 
68If you see `Failed to read calendar events`, verify Calendar is set to **Full Calendar Access**:
69 
70- Open `System Settings > Privacy & Security > Calendars`
71- Find the app that launches this MCP server (for example Terminal or Claude Desktop)
72- Change access to **Full Calendar Access**
73 
74You can also re-run `./check-permissions.sh` (it now validates both Reminders and Calendars access).
75 
76**Verification command**
77 
78```bash
79pnpm test -- src/swift/Info.plist.test.ts
80```
81 
82The test suite ensures all required usage-description strings are present before shipping the binary.
83 
84## Quick Start
85 
86You can run the server directly using `npx`:
87 
88```bash
89npx mcp-server-apple-events
90```
91 
92## Configuration
93 
94### Configure Cursor
95 
961. Open Cursor
972. Open Cursor settings
983. Click on "MCP" in the sidebar
994. Click "Add new global MCP server"
1005. Configure the server with the following settings:
101 
102   ```json
103   {
104     "mcpServers": {
105       "apple-reminders": {
106         "command": "npx",
107         "args": ["-y", "mcp-server-apple-events"]
108       }
109     }
110   }
111   ```
112 
113### Configure ChatWise
114 
1151. Open ChatWise
1162. Go to Settings
1173. Navigate to the Tools section
1184. Click the "+" button
1195. Configure the tool with the following settings:
120   - Type: `stdio`
121   - ID: `apple-reminders`
122   - Command: `mcp-server-apple-events`
123   - Args: (leave empty)
124 
125### Configure Claude Desktop
126 
127You need to configure Claude Desktop to recognize the Apple Events MCP server. There are two ways to access the configuration:
128 
129#### Option 1: Through Claude Desktop UI
130 
1311. Open Claude Desktop app
1322. Enable Developer Mode from the top-left menu bar
1333. Open Settings and navigate to the Developer Option
1344. Click the Edit Config button to open `claude_desktop_config.json`
135 
136#### Option 2: Direct File Access
137 
138For macOS:
139 
140```bash
141code ~/Library/Application\ Support/Claude/claude_desktop_config.json
142```
143 
144For Windows:
145 
146```bash
147code %APPDATA%\Claude\claude_desktop_config.json
148```
149 
150### 2. Add Server Configuration
151 
152Add the following configuration to your `claude_desktop_config.json`:
153 
154**Option A: Using npx (recommended)**
155 
156```json
157{
158  "mcpServers": {
159    "apple-reminders": {
160      "command": "npx",
161      "args": ["-y", "mcp-server-apple-events"]
162    }
163  }
164}
165```
166 
167**Option B: Using local build**
168 
169If you have built the project locally, use node with the path to run.cjs:
170 
171```json
172{
173  "mcpServers": {
174    "apple-reminders": {
175      "command": "node",
176      "args": ["/absolute/path/to/mcp-server-apple-events/bin/run.cjs"]
177    }
178  }
179}
180```
181 
182For more information on connecting local MCP servers, see the
183[official MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers).
184 
185### 3. Restart Claude Desktop
186 
187For the changes to take effect:
188 
1891. Completely quit Claude Desktop (not just close the window)
1902. Start Claude Desktop again
1913. Look for the tool icon to verify the Apple Events server is connected
192 
193## Usage Examples
194 
195Once configured, you can ask Claude to interact with your Apple Reminders. Here are some example prompts:
196 
197### Creating Reminders
198 
199```text
200Create a reminder to "Buy groceries" for tomorrow at 5 PM.
201Add a reminder to "Call mom" with a note "Ask about weekend plans".
202Create a reminder in my "Work" list to "Submit report" due next Friday.
203Create a reminder with URL "Check this website: https://google.com".
204```
205 
206### Creating Reminders with Priority
207 
208```text
209Create a high priority reminder to "Finish quarterly report" due Friday.
210Add an urgent high-priority reminder to "Call client back" for today.
211Create a medium priority reminder to "Review documents".
212```
213 
214### Creating Recurring Reminders
215 
216```text
217Create a daily reminder to "Take medication" at 9 AM.
218Add a weekly reminder every Monday to "Team standup meeting".
219Create a monthly reminder on the 1st to "Pay rent".
220Set up a yearly reminder on March 15 to "File taxes".
221```
222 
223### Creating Location-Based Reminders
224 
225```text
226Remind me to "Buy milk" when I arrive at the grocery store.
227Create a reminder to "Check mailbox" when I get home.
228Add a reminder to "Submit timesheet" when I leave the office.
229```
230 
231### Creating Reminders with Tags
232 
233```text
234Create a reminder "Review PR" with tags work and urgent.
235Add a reminder "Buy birthday gift" tagged personal and shopping.
236Create a reminder with tags: project-alpha, backend, review.
237```
238 
239### Creating Reminders with Subtasks
240 
241```text
242Create a reminder "Grocery shopping" with subtasks: milk, eggs, bread, butter.
243Add a reminder "Pack for trip" with checklist items: passport, charger, clothes, toiletries.
244Create "Sprint planning" with subtasks: review backlog, estimate stories, assign tasks.
245```
246 
247### Managing Subtasks
248 
249```text
250Show subtasks for my "Grocery shopping" reminder.
251Mark the "milk" subtask as complete.
252Add a new subtask "cheese" to my grocery list reminder.
253Reorder the subtasks in my packing list.
254```
255 
256### Filtering Reminders
257 
258```text
259Show me all high priority reminders.
260Show reminders tagged with "work".
261Show recurring reminders only.
262Find location-based reminders.
263Show reminders with incomplete subtasks.
264```
265 
266### Update Reminders
267 
268```text
269Update the reminder "Buy groceries" with a new title "Buy organic groceries".
270Update "Call mom" reminder to be due today at 6 PM.
271Update the reminder "Submit report" and mark it as completed.
272Change the notes on "Buy groceries" to "Don't forget milk and eggs".
273Set priority to high on my "Finish report" reminder.
274Add the tag "urgent" to my "Review PR" reminder.
275```
276 
277### Managing Reminders
278 
279```text
280Show me all my reminders.
281List all reminders in my "Shopping" list.
282Show my completed reminders.
283```
284 
285### Working with Lists
286 
287```text
288Show all my reminder lists.
289Show reminders from my "Work" list.
290```
291 
292The server will:
293 
294- Process your natural language requests
295- Interact with Apple's native Reminders app
296- Return formatted results to Claude
297- Maintain native integration with macOS
298 
299## Structured Prompt Library
300 
301The server ships with a consolidated prompt registry exposed via the MCP `ListPrompts` and `GetPrompt` endpoints. Each template shares a mission, context inputs, numbered process, constraints, output format, and quality bar so downstream assistants receive predictable scaffolding instead of brittle free-form examples.
302 
303- **daily-task-organizer** — optional `today_focus` (what you most want to accomplish today) input produces a same-day execution blueprint that keeps priority work balanced with recovery time. Supports intelligent task clustering, focus block scheduling, automatic reminder list organization, and auto-creates calendar time blocks when many due-today reminders need fixed slots. Quick Win clusters become 15-minute "Focus Sprint — [Outcome]" holds that finish at each reminder's due timestamp, while Standard tasks map to 30-, 45-, or 60-minute events anchored to the same due-time window.
304- **smart-reminder-creator** — optional `task_idea` (a short description of what you want to do) generates an optimally scheduled reminder structure.
305- **reminder-review-assistant** — optional `review_focus` (e.g., overdue or a list name) to audit and optimize existing reminders.
306- **weekly-planning-workflow** — optional `user_ideas` (your thoughts and ideas for what you want to accomplish this week) guides a Monday-through-Sunday reset with time blocks tied to existing lists.
307 
308### Design constraints and validation
309 
310- Prompts are intentionally constrained to native Apple Reminders capabilities (no third-party automations) and ask for missing context before committing to irreversible actions.
311- Shared formatting keeps outputs renderable as Markdown sections or tables without extra parsing glue in client applications.
312- Run `pnpm test -- src/server/prompts.test.ts` to assert metadata, schema compatibility, and narrative assembly each time you amend prompt copy.
313 
314## Available MCP Tools
315 
316This server now exposes service-scoped MCP tools that mirror Apple Reminders and Calendar domains. Use the identifier that matches the resource you want to manipulate:
317 
318### Reminder Tasks Tool
319 
320**Tool Name**: `reminders_tasks`
321 
322Manages individual reminder tasks with full CRUD support, including priority, alarms, recurrence rules, start/due/completion dates, location triggers, tags, and subtasks.
323 
324**Actions**: `read`, `create`, `update`, `delete`
325 
326**Main Handler Functions**:
327 
328- `handleReadReminders()` - Read reminders with filtering options
329- `handleCreateReminder()` - Create new reminders
330- `handleUpdateReminder()` - Update existing reminders
331- `handleDeleteReminder()` - Delete reminders
332 
333#### Parameters by Action
334 
335**Read Action** (`action: "read"`):
336 
337- `id` _(optional)_: Unique identifier of a specific reminder to read
338- `filterList` _(optional)_: Name of the reminder list to show
339- `showCompleted` _(optional)_: Include completed reminders (default: false)
340- `search` _(optional)_: Search term to filter reminders by title or content
341- `dueWithin` _(optional)_: Filter by due date range ("today", "tomorrow", "this-week", "overdue", "no-date")
342- `filterPriority` _(optional)_: Filter by priority level ("high", "medium", "low", "none")
343- `filterRecurring` _(optional)_: Filter to only show recurring reminders when true
344- `filterLocationBased` _(optional)_: Filter to only show location-based reminders when true
345- `filterTags` _(optional)_: Filter by tags (reminders must have ALL specified tags)
346 
347**Create Action** (`action: "create"`):
348 
349- `title` _(required)_: Title of the reminder
350- `startDate` _(optional)_: Start date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'
351- `dueDate` _(optional)_: Due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'
352- `targetList` _(optional)_: Name of the reminders list to add to
353- `note` _(optional)_: Note text to attach to the reminder
354- `url` _(optional)_: URL to associate with the reminder
355- `location` _(optional)_: Location text (`EKCalendarItem.location`) (not a geofence trigger)
356- `priority` _(optional)_: Priority level (0=none, 1=high, 2=medium, 3=low)
357- `alarms` _(optional)_: Array of alarm objects (see Alarm Object below)
358- `recurrenceRules` _(optional)_: Array of recurrence rules (see Recurrence Rules below)
359- `recurrence` _(optional)_: Legacy single recurrence rule object (shorthand for one-item `recurrenceRules`)
360- `locationTrigger` _(optional)_: Location trigger object (see Location Triggers section below)
361- `tags` _(optional)_: Array of tags to add to the reminder
362- `subtasks` _(optional)_: Array of subtask titles to create with the reminder
363 
364**Update Action** (`action: "update"`):
365 
366- `id` _(required)_: Unique identifier of the reminder to update
367- `title` _(optional)_: New title for the reminder
368- `startDate` _(optional)_: New start date
369- `dueDate` _(optional)_: New due date in format 'YYYY-MM-DD' or 'YYYY-MM-DD HH:mm:ss'
370- `note` _(optional)_: New note text
371- `url` _(optional)_: New URL to attach to the reminder
372- `location` _(optional)_: New location text (set to empty string to clear)
373- `completed` _(optional)_: Mark reminder as completed/uncompleted
374- `completionDate` _(optional)_: Set an explicit completion date/time
375- `targetList` _(optional)_: Name of the list containing the reminder
376- `priority` _(optional)_: New priority level (0=none, 1=high, 2=medium, 3=low)
377- `alarms` _(optional)_: Replace alarms with this array
378- `clearAlarms` _(optional)_: Set to true to remove all alarms
379- `recurrenceRules` _(optional)_: Replace recurrence rules with this array
380- `recurrence` _(optional)_: Legacy single recurrence rule (shorthand for one-item `recurrenceRules`)
381- `clearRecurrence` _(optional)_: Set to true to remove recurrence
382- `locationTrigger` _(optional)_: New location trigger
383- `clearLocationTrigger` _(optional)_: Set to true to remove location trigger
384- `tags` _(optional)_: Replace all tags with this array
385- `addTags` _(optional)_: Tags to add (merges with existing)
386- `removeTags` _(optional)_: Tags to remove
387 
388**Delete Action** (`action: "delete"`):
389 
390- `id` _(required)_: Unique identifier of the reminder to delete
391 
392#### Alarm Object
393 
394```json
395{
396  "relativeOffset": -900,            // Seconds (relative to due/start); negative = before
397  "absoluteDate": "2025-11-04T09:00:00+08:00", // Absolute trigger time (optional)
398  "locationTrigger": {               // Geofence trigger (optional)
399    "title": "Office",
400    "latitude": 37.7749,
401    "longitude": -122.4194,
402    "radius": 100,
403    "proximity": "enter"
404  }
405}
406```
407 
408Each alarm must specify exactly **one** of `relativeOffset`, `absoluteDate`, or `locationTrigger`.
409 
410#### Recurrence Rule Object (for `recurrenceRules`)
411 
412```json
413{
414  "frequency": "daily" | "weekly" | "monthly" | "yearly",
415  "interval": 1,           // Every N periods (default: 1)
416  "endDate": "YYYY-MM-DD", // Optional end date
417  "occurrenceCount": 10,   // Optional max occurrences
418  "daysOfWeek": [1, 3, 5], // 1=Sunday, 7=Saturday (for weekly)
419  "daysOfMonth": [1, 15],  // 1-31 (for monthly)
420  "monthsOfYear": [3, 6]   // 1-12 (for yearly)
421}
422```
423 
424#### Location Trigger Object
425 
426```json
427{
428  "title": "Home", // Location name
429  "latitude": 37.7749, // Latitude coordinate
430  "longitude": -122.4194, // Longitude coordinate
431  "radius": 100, // Geofence radius in meters (default: 100)
432  "proximity": "enter" // "enter" or "leave"
433}
434```
435 
436#### Example Usage
437 
438```json
439{
440  "action": "create",
441  "title": "Buy groceries",
442  "dueDate": "2024-03-25 18:00:00",
443  "targetList": "Shopping",
444  "note": "Don't forget milk and eggs",
445  "priority": 1,
446  "tags": ["shopping", "errands"],
447  "subtasks": ["Milk", "Eggs", "Bread"]
448}
449```
450 
451```json
452{
453  "action": "create",
454  "title": "Team standup",
455  "dueDate": "2024-03-25 09:00:00",
456  "recurrence": {
457    "frequency": "weekly",
458    "interval": 1,
459    "daysOfWeek": [2, 3, 4, 5, 6]
460  }
461}
462```
463 
464```json
465{
466  "action": "create",
467  "title": "Buy milk",
468  "locationTrigger": {
469    "title": "Grocery Store",
470    "latitude": 37.7749,
471    "longitude": -122.4194,
472    "radius": 200,
473    "proximity": "enter"
474  }
475}
476```
477 
478```json
479{
480  "action": "read",
481  "filterList": "Work",
482  "showCompleted": false,
483  "dueWithin": "today",
484  "filterPriority": "high",
485  "filterTags": ["urgent"]
486}
487```
488 
489```json
490{
491  "action": "delete",
492  "id": "reminder-123"
493}
494```
495 
496### Reminder Subtasks Tool
497 
498**Tool Name**: `reminders_subtasks`
499 
500Manages subtasks/checklists within reminders. Subtasks are stored in the notes field using a human-readable format visible in the native Reminders app.
501 
502**Actions**: `read`, `create`, `update`, `delete`, `toggle`, `reorder`
503 
504**Main Handler Functions**:
505 
506- `handleReadSubtasks()` - List all subtasks for a reminder
507- `handleCreateSubtask()` - Add a new subtask
508- `handleUpdateSubtask()` - Modify a subtask
509- `handleDeleteSubtask()` - Remove a subtask
510- `handleToggleSubtask()` - Flip completion status
511- `handleReorderSubtasks()` - Change subtask order
512 
513#### Parameters by Action
514 
515**Read Action** (`action: "read"`):
516 
517- `reminderId` _(required)_: Parent reminder ID
518 
519**Create Action** (`action: "create"`):
520 
521- `reminderId` _(required)_: Parent reminder ID
522- `title` _(required)_: Subtask title
523 
524**Update Action** (`action: "update"`):
525 
526- `reminderId` _(required)_: Parent reminder ID
527- `subtaskId` _(required)_: Subtask ID to update
528- `title` _(optional)_: New title
529- `completed` _(optional)_: New completion status
530 
531**Delete Action** (`action: "delete"`):
532 
533- `reminderId` _(required)_: Parent reminder ID
534- `subtaskId` _(required)_: Subtask ID to delete
535 
536**Toggle Action** (`action: "toggle"`):
537 
538- `reminderId` _(required)_: Parent reminder ID
539- `subtaskId` _(required)_: Subtask ID to toggle
540 
541**Reorder Action** (`action: "reorder"`):
542 
543- `reminderId` _(required)_: Parent reminder ID
544- `order` _(required)_: Array of all subtask IDs in desired order
545 
546#### Example Usage
547 
548```json
549{
550  "action": "read",
551  "reminderId": "reminder-123"
552}
553```
554 
555```json
556{
557  "action": "create",
558  "reminderId": "reminder-123",
559  "title": "Pick up dry cleaning"
560}
561```
562 
563```json
564{
565  "action": "toggle",
566  "reminderId": "reminder-123",
567  "subtaskId": "a1b2c3d4"
568}
569```
570 
571#### Subtask Storage Format
572 
573Subtasks are stored in the notes field with this human-readable format:
574 
575```text
576User notes here...
577 
578---SUBTASKS---
579[ ] {a1b2c3d4} First task
580[x] {e5f6g7h8} Completed task
581[ ] {i9j0k1l2} Another task
582---END SUBTASKS---
583```
584 
585This format ensures subtasks are visible in the native Reminders app while enabling programmatic access.
586 
587### Reminder Lists Tool
588 
589**Tool Name**: `reminders_lists`
590 
591Manages reminder lists - view existing lists or create new ones for organizing reminders.
592 
593**Actions**: `read`, `create`, `update`, `delete`
594 
595**Main Handler Functions**:
596 
597- `handleReadReminderLists()` - Read all reminder lists
598- `handleCreateReminderList()` - Create new reminder lists
599- `handleUpdateReminderList()` - Update existing reminder lists
600- `handleDeleteReminderList()` - Delete reminder lists
601 
602#### Parameters by Action
603 
604**Read Action** (`action: "read"`):
605 
606- No additional parameters required
607 
608**Create Action** (`action: "create"`):
609 
610- `name` _(required)_: Name for new reminder list
611 
612**Update Action** (`action: "update"`):
613 
614- `name` _(required)_: Current name of the list to update
615- `newName` _(required)_: New name for the reminder list
616 
617**Delete Action** (`action: "delete"`):
618 
619- `name` _(required)_: Name of the list to delete
620 
621#### Example Usage
622 
623```json
624{
625  "action": "create",
626  "name": "Project Alpha"
627}
628```
629 
630### Calendar Events Tool
631 
632**Tool Name**: `calendar_events`
633 
634Handles EventKit calendar events (time blocks) with CRUD capabilities.
635 
636**Actions**: `read`, `create`, `update`, `delete`
637 
638**Main Handler Functions**:
639 
640- `handleReadCalendarEvents()` - Read events with optional filters
641- `handleCreateCalendarEvent()` - Create calendar events
642- `handleUpdateCalendarEvent()` - Update existing events
643- `handleDeleteCalendarEvent()` - Delete calendar events
644 
645#### Parameters by Action
646 
647**Read Action** (`action: "read"`):
648 
649- `id` _(optional)_: Unique identifier of an event to read
650- `filterCalendar` _(optional)_: Calendar name filter
651- `search` _(optional)_: Keyword match against title, notes, or location
652- `availability` _(optional)_: Filter by availability ("busy", "free", "tentative", "unavailable", "not-supported")
653- `startDate` _(optional)_: Filter events starting on/after this date
654- `endDate` _(optional)_: Filter events ending on/before this date
655 
656**Create Action** (`action: "create"`):
657 
658- `title` _(required)_: Event title
659- `startDate` _(required)_: Start date/time
660- `endDate` _(required)_: End date/time
661- `targetCalendar` _(optional)_: Calendar name to create in
662- `note`, `location`, `structuredLocation`, `url`, `isAllDay` _(optional)_: Additional metadata
663- `availability` _(optional)_: Availability ("busy", "free", "tentative", "unavailable")
664- `alarms` _(optional)_: Array of alarm objects (see Alarm Object above)
665- `recurrenceRules` _(optional)_: Array of recurrence rules (see Recurrence Rule Object above)
666 
667**Update Action** (`action: "update"`):
668 
669- `id` _(required)_: Event identifier
670- Other fields align with create parameters and are optional updates
671- `clearAlarms` _(optional)_: Set to true to remove all alarms
672- `clearRecurrence` _(optional)_: Set to true to remove all recurrence rules
673- `span` _(optional)_: Scope for recurring event changes: `"this-event"` or `"future-events"`
674 
675**Delete Action** (`action: "delete"`):
676 
677- `id` _(required)_: Event identifier to remove
678- `span` _(optional)_: Scope for recurring event deletes: `"this-event"` or `"future-events"`
679 
680### Calendar Collections Tool
681 
682**Tool Name**: `calendar_calendars`
683 
684Returns the available calendars from EventKit. This is useful before creating or updating events to confirm calendar identifiers.
685 
686**Actions**: `read`
687 
688**Main Handler Function**:
689 
690- `handleReadCalendars()` - List all calendars with IDs and titles
691 
692**Example Usage**
693 
694```json
695{
696  "action": "read"
697}
698```
699 
700**Example Response**
701 
702```json
703{
704  "content": [
705    {
706      "type": "text",
707      "text": "### Calendars (Total: 3)\n- Work (ID: cal-1)\n- Personal (ID: cal-2)\n- Shared (ID: cal-3)"
708    }
709  ],
710  "isError": false
711}
712```
713 
714#### Response Formats
715 
716**Success Response**:
717 
718```json
719{
720  "content": [
721    {
722      "type": "text",
723      "text": "Successfully created reminder: Buy groceries"
724    }
725  ],
726  "isError": false
727}
728```
729 
730**Reminder with Enhanced Features**:
731 
732When reading reminders, the output includes visual indicators for enhanced features:
733 
734- 🔄 - Recurring reminder
735- 📍 - Location-based reminder
736- 🏷️ - Has tags
737- 📋 - Has subtasks
738 
739Example output:
740 
741```text
742- [ ] Buy groceries 🏷️📋
743  - List: Shopping
744  - ID: reminder-123
745  - Priority: high
746  - Tags: #shopping #errands
747  - Subtasks (1/3):
748    - [x] Milk
749    - [ ] Eggs
750    - [ ] Bread
751  - Due: 2024-03-25 18:00:00
752```
753 
754**Note about URL fields**: The `url` field is fully supported by EventKit API. When you create or update a reminder with a URL parameter, the URL is stored in two places for maximum compatibility:
755 
7561. **EventKit URL field**: The URL is stored in the native `url` property (visible in Reminders app detail view via the "i" icon)
7572. **Notes field**: The URL is also appended to the notes using a structured format for parsing
758 
759**Dual Storage Approach**:
760 
761- **URL field**: Stores a single URL for native Reminders app display
762- **Notes field**: Stores URLs in a structured format for parsing and multiple URL support
763 
764```text
765Reminder note content here...
766 
767URLs:
768- https://example.com
769- https://another-url.com
770```
771 
772This ensures URLs are accessible both in the Reminders app UI and through the API/notes for parsing.
773 
774**URL Extraction**: You can extract URLs from reminder notes using regex:
775 
776```typescript
777// Extract URLs from notes using regex
778const urlsRegex = reminder.notes?.match(/https?:\/\/[^\s]+/g) || [];
779```
780 
781**Benefits of Structured Format**:
782 
783- **Consistent parsing**: URLs are always in a predictable location
784- **Multiple URL support**: Handle multiple URLs per reminder reliably
785- **Clean separation**: Note content and URLs are clearly separated
786- **Backward compatible**: Unstructured URLs still detected as fallback
787 
788**List Response**:
789 
790```json
791{
792  "reminders": [
793    {
794      "title": "Buy groceries",
795      "list": "Shopping",
796      "isCompleted": false,
797      "dueDate": "2024-03-25 18:00:00",
798      "priority": 1,
799      "tags": ["shopping", "errands"],
800      "subtasks": [
801        { "id": "a1b2c3d4", "title": "Milk", "isCompleted": true },
802        { "id": "e5f6g7h8", "title": "Eggs", "isCompleted": false }
803      ],
804      "subtaskProgress": { "completed": 1, "total": 2, "percentage": 50 },
805      "notes": "Don't forget the organic options",
806      "url": null
807    }
808  ],
809  "total": 1,
810  "filter": {
811    "list": "Shopping",
812    "showCompleted": false
813  }
814}
815```
816 
817## Organization Strategies
818 
819The server provides intelligent reminder organization capabilities through four built-in strategies:
820 
821### Priority Strategy
822 
823Automatically categorizes reminders based on priority keywords:
824 
825- **High Priority**: Contains words like "urgent", "important", "critical", "asap"
826- **Medium Priority**: Default category for standard reminders
827- **Low Priority**: Contains words like "later", "someday", "eventually", "maybe"
828 
829### Due Date Strategy
830 
831Organizes reminders based on their due dates:
832 
833- **Overdue**: Past due dates
834- **Today**: Due today
835- **Tomorrow**: Due tomorrow
836- **This Week**: Due within the current week
837- **Next Week**: Due next week
838- **Future**: Due beyond next week
839- **No Date**: Reminders without due dates
840 
841### Category Strategy
842 
843Intelligently categorizes reminders by content analysis:
844 
845- **Work**: Business, meetings, projects, office, client related
846- **Personal**: Home, family, friends, self-care related
847- **Shopping**: Buy, store, purchase, groceries related
848- **Health**: Doctor, exercise, medical, fitness, workout related
849- **Finance**: Bills, payments, bank, budget related
850- **Travel**: Trips, flights, hotels, vacation related
851- **Education**: Study, learn, courses, books, research related
852- **Uncategorized**: Doesn't match any specific category
853 
854### Completion Status Strategy
855 
856Simple binary organization:
857 
858- **Active**: Incomplete reminders
859- **Completed**: Finished reminders
860 
861### Usage Examples
862 
863Organize all reminders by priority:
864 
865```text
866Organize my reminders by priority
867```
868 
869Categorize work-related reminders:
870 
871```text
872Organize reminders from Work list by category
873```
874 
875Sort overdue items:
876 
877```text
878Organize overdue reminders by due date
879```
880 
881## Tags System
882 
883Tags provide cross-list categorization for reminders. They are stored in the notes field using the `[#tag]` format, which keeps them human-readable in the native Reminders app.
884 
885### Tag Format
886 
887Tags are stored at the end of notes:
888 
889```text
890User notes here...
891 
892[#work] [#urgent] [#project-alpha]
893```
894 
895### Tag Rules
896 
897- Tags can contain letters, numbers, underscores, and hyphens
898- Maximum 50 characters per tag
899- Case-sensitive
900- Filter by multiple tags uses AND logic (reminder must have ALL specified tags)
901 
902### Example Tag Operations
903 
904Create with tags:
905 
906```json
907{
908  "action": "create",
909  "title": "Review code",
910  "tags": ["work", "code-review", "urgent"]
911}
912```
913 
914Filter by tags:
915 
916```json
917{
918  "action": "read",
919  "filterTags": ["work", "urgent"]
920}
921```
922 
923Update tags (add/remove):
924 
925```json
926{
927  "action": "update",
928  "id": "reminder-123",
929  "addTags": ["completed"],
930  "removeTags": ["urgent"]
931}
932```
933 
934## License
935 
936MIT
937 
938## Contributing
939 
940Contributions welcome! Please read the contributing guidelines first.
941 
942## Development
943 
9441. Install dependencies with pnpm (keeps the Swift bridge and TypeScript graph in sync):
945 
946```bash
947pnpm install
948```
949 
9501. Build the project (TypeScript and Swift binary) before invoking the CLI:
951 
952```bash
953pnpm build
954```
955 
9561. Run the full test suite to validate TypeScript, Swift bridge shims, and prompt templates:
957 
958```bash
959pnpm test
960```
961 
9621. Lint and format with Biome prior to committing:
963 
964```bash
965pnpm exec biome check
966```
967 
968### Launching from nested directories
969 
970The CLI entry point includes a project-root fallback, so you can start the server from nested paths (for example `dist/` or editor task runners) without losing access to the bundled Swift binary. The bootstrapper walks up to ten directories to find `package.json`; if you customise the folder layout, keep the manifest reachable within that depth to retain the guarantee.
971 
972### Available Scripts
973 
974- `pnpm build` - Build the Swift helper binary (required before starting the server)
975- `pnpm build:swift` - Build the Swift helper binary only
976- `pnpm dev` - TypeScript development mode with file watching via tsx (runtime TS execution)
977- `pnpm start` - Start the MCP server over stdio (auto-fallback to runtime TS if no build)
978- `pnpm test` - Run the comprehensive Jest test suite
979- `pnpm check` - Run Biome formatting and TypeScript type checking
980 
981### Dependencies
982 
983**Runtime Dependencies:**
984 
985- `@modelcontextprotocol/sdk ^1.25.1` - MCP protocol implementation
986- `exit-on-epipe ^1.0.1` - Graceful process termination handling
987- `tsx ^4.21.0` - TypeScript execution and REPL
988- `zod ^4.3.5` - Runtime type validation
989 
990**Development Dependencies:**
991 
992- `typescript ^5.9.3` - TypeScript compiler
993- `@types/node ^25.0.3` - Node.js type definitions
994- `@types/jest ^30.0.0` - Jest type definitions
995- `jest ^30.2.0` - Testing framework
996- `babel-jest ^30.2.0` - Babel Jest transformer
997- `babel-plugin-transform-import-meta ^2.3.3` - Babel import meta transform
998- `ts-jest ^29.4.6` - Jest TypeScript support
999- `@biomejs/biome ^2.3.11` - Code formatting and linting
1000 
1001**Build Tools:**
1002 
1003- Swift binaries for native macOS integration
1004- TypeScript compilation for cross-platform compatibility
1005