Advanced Features

• Smart Organization: Automatic categorization and intelligent filtering by priority, due date, category, or completion status
• Powerful Search: Multi-criteria filtering including completion status, due date ranges, tags, and full-text search
• Batch Operations: Efficient handling of multiple reminders with optimized data access patterns
• Permission Management: Automatic validation and request for required macOS system permissions
• Flexible Date Handling: Support for multiple date formats (YYYY-MM-DD, ISO 8601) with timezone awareness
• Unicode Support: Full international character support with comprehensive input validation

Technical Excellence

• Clean Architecture: 4-layer architecture following Clean Architecture principles with dependency injection
• Type Safety: Complete TypeScript coverage with Zod schema validation for runtime type checking
• High Performance: Swift-compiled binaries for performance-critical Apple Reminders operations
• Robust Error Handling: Consistent error responses with detailed diagnostic information
• Repository Pattern: Data access abstraction with standardized CRUD operations
• Functional Programming: Pure functions with immutable data structures where appropriate

Prerequisites

• Node.js 18 or later
• macOS (required for Apple Reminders integration)
• Xcode Command Line Tools (required for compiling Swift code)
• pnpm (recommended for package management)

macOS Permission Requirements (Sonoma 14+ / Sequoia 15)

Apple 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:

• NSRemindersUsageDescription
• NSRemindersFullAccessUsageDescription
• NSRemindersWriteOnlyAccessUsageDescription
• NSCalendarsUsageDescription
• NSCalendarsFullAccessUsageDescription
• NSCalendarsWriteOnlyAccessUsageDescription

When 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.

If 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.

Troubleshooting Calendar Read Errors

If you see Failed to read calendar events, verify Calendar is set to Full Calendar Access:

• Open System Settings > Privacy & Security > Calendars
• Find the app that launches this MCP server (for example Terminal or Claude Desktop)
• Change access to Full Calendar Access

You can also re-run ./check-permissions.sh (it now validates both Reminders and Calendars access).

Verification command

pnpm test -- src/swift/Info.plist.test.ts

The test suite ensures all required usage-description strings are present before shipping the binary.

Quick Start

You can run the server directly using npx:

npx mcp-server-apple-events

Configuration

Configure Cursor

1. Open Cursor

2. Open Cursor settings

3. Click on "MCP" in the sidebar

4. Click "Add new global MCP server"

5. Configure the server with the following settings:

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

Configure ChatWise

1. Open ChatWise
2. Go to Settings
3. Navigate to the Tools section
4. Click the "+" button
5. Configure the tool with the following settings:
   • Type: stdio
   • ID: apple-reminders
   • Command: mcp-server-apple-events
   • Args: (leave empty)

Configure Claude Desktop

You need to configure Claude Desktop to recognize the Apple Events MCP server. There are two ways to access the configuration:

Option 1: Through Claude Desktop UI

1. Open Claude Desktop app
2. Enable Developer Mode from the top-left menu bar
3. Open Settings and navigate to the Developer Option
4. Click the Edit Config button to open claude_desktop_config.json

Option 2: Direct File Access

For macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

For Windows:

code %APPDATA%\Claude\claude_desktop_config.json

2. Add Server Configuration

Add the following configuration to your claude_desktop_config.json:

Option A: Using npx (recommended)

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

Option B: Using local build

If you have built the project locally, use node with the path to run.cjs:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-apple-events/bin/run.cjs"]
    }
  }
}

For more information on connecting local MCP servers, see the official MCP documentation.

3. Restart Claude Desktop

For the changes to take effect:

1. Completely quit Claude Desktop (not just close the window)
2. Start Claude Desktop again
3. Look for the tool icon to verify the Apple Events server is connected

Usage Examples

Once configured, you can ask Claude to interact with your Apple Reminders. Here are some example prompts:

Creating Reminders

Create a reminder to "Buy groceries" for tomorrow at 5 PM.
Add a reminder to "Call mom" with a note "Ask about weekend plans".
Create a reminder in my "Work" list to "Submit report" due next Friday.
Create a reminder with URL "Check this website: https://google.com".

Creating Reminders with Priority

Create a high priority reminder to "Finish quarterly report" due Friday.
Add an urgent high-priority reminder to "Call client back" for today.
Create a medium priority reminder to "Review documents".

Creating Recurring Reminders

Create a daily reminder to "Take medication" at 9 AM.
Add a weekly reminder every Monday to "Team standup meeting".
Create a monthly reminder on the 1st to "Pay rent".
Set up a yearly reminder on March 15 to "File taxes".

Creating Location-Based Reminders

Remind me to "Buy milk" when I arrive at the grocery store.
Create a reminder to "Check mailbox" when I get home.
Add a reminder to "Submit timesheet" when I leave the office.

Creating Reminders with Tags

Create a reminder "Review PR" with tags work and urgent.
Add a reminder "Buy birthday gift" tagged personal and shopping.
Create a reminder with tags: project-alpha, backend, review.

Creating Reminders with Subtasks

Create a reminder "Grocery shopping" with subtasks: milk, eggs, bread, butter.
Add a reminder "Pack for trip" with checklist items: passport, charger, clothes, toiletries.
Create "Sprint planning" with subtasks: review backlog, estimate stories, assign tasks.

Managing Subtasks

Show subtasks for my "Grocery shopping" reminder.
Mark the "milk" subtask as complete.
Add a new subtask "cheese" to my grocery list reminder.
Reorder the subtasks in my packing list.

Filtering Reminders

Show me all high priority reminders.
Show reminders tagged with "work".
Show recurring reminders only.
Find location-based reminders.
Show reminders with incomplete subtasks.

Update Reminders

Update the reminder "Buy groceries" with a new title "Buy organic groceries".
Update "Call mom" reminder to be due today at 6 PM.
Update the reminder "Submit report" and mark it as completed.
Change the notes on "Buy groceries" to "Don't forget milk and eggs".
Set priority to high on my "Finish report" reminder.
Add the tag "urgent" to my "Review PR" reminder.

Managing Reminders

Show me all my reminders.
List all reminders in my "Shopping" list.
Show my completed reminders.

Working with Lists

Show all my reminder lists.
Show reminders from my "Work" list.

The server will:

• Process your natural language requests
• Interact with Apple's native Reminders app
• Return formatted results to Claude
• Maintain native integration with macOS

Structured P