Apple Events MCP Server

English | 简体中文

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

[!NOTE] Looking ahead: event — a pure Swift CLI for Apple Reminders and Calendar on macOS.

For scripting, automation, and direct terminal usage, we now recommend the standalone event CLI. It exposes the same EventKit-backed reminder/calendar/list/subtask/tag operations this server uses today, with first-class Markdown and JSON output. Future versions of mcp-server-apple-events are planned to depend on the event CLI in place of the bundled EventKitCLI binary, so both projects can share a single, well-tested Swift implementation.

Features

Core Functionality

• List Management: View all reminders and reminder lists with advanced filtering options
• Reminder Operations: Full CRUD operations (Create, Read, Update, Delete) for reminders across lists
• Rich Content Support: Complete support for titles, notes, due dates, URLs, and completion status
• Native macOS Integration: Direct integration with Apple Reminders using EventKit framework

Enhanced Reminder Features (v1.3.0)

• Priority Support: Set reminder priority (high/medium/low/none) with visual indicators
• Recurring Reminders: Create repeating reminders with flexible recurrence rules (daily, weekly, monthly, yearly)
• Location-Based Triggers: Set geofence reminders that trigger when arriving at or leaving a location
• Tags/Labels: Organize reminders with custom tags for cross-list categorization and filtering
• Subtasks/Checklists: Add checklist items to reminders with progress tracking

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 20 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, see Desktop MCP clients below for the responsible-process attribution problem and the recommended workarounds.

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

Desktop MCP clients (Claude Desktop, Codex Desktop, …)

macOS attributes Reminders and Calendar access to the responsible process — the desktop app that launched the MCP server, not the EventKitCLI subprocess. For the EventKit prompt to appear, the responsible app's bundle must ship the NSRemindersUsageDescription / NSCalendarsUsageDescription keys (and on Sonoma+ the matching write-only or full-access variants). If those keys are missing, TCC refuses the request before EventKit is even reached, and the Swift CLI returns:

Reminder permission denied. Unknown error

— even though running the same binary from Terminal works. See issue #93 for the full TCC log; Codex Desktop today ships only NSAppleEventsUsageDescription, which is why it hits this wall.

This is a macOS-level constraint that an MCP server alone cannot resolve — the desktop client itself needs to declare those usage strings in its Info.plist. The workarounds below are about making the server usable while you wait for the upstream fix:

Reliable workaround — run the server from a terminal-based MCP client. Codex CLI, Claude Code, and similar terminal-launched clients inherit Terminal's (or iTerm2's) own kTCCServiceReminders / kTCCServiceCalendar grant, so EventKit calls succeed without changes to this server:

# from inside Terminal / iTerm2, where the responsible app holds the EventKit grants
codex
# or
claude

Partial workaround — AppleScript routing (only if the desktop app already declares NSAppleEventsUsageDescription). Running:

osascript -e 'tell application "Reminders" to get name of lists'
osascript -e 'tell application "Calendar" to get name of calendars'

triggers an Automation prompt (kTCCServiceAppleEvents) so the responsible app can control com.apple.reminders and com.apple.iCal. This does not create a kTCCServiceReminders / kTCCServiceCalendar grant on its own, so a Swift CLI that calls EventKit directly will still be refused if the host bundle is missing the usage strings. It only helps if your client can fall back to AppleScript end-to-end (this server does not today).

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.

Troubleshooting could not build module 'Foundation' on macOS 26 (Tahoe)

If pnpm build fails with could not build module 'Foundation' (or SDK is not supported by the compiler), your Swift toolchain is older than the macOS 26 SDK requires. The macOS 26+ SDK ships a Foundation.swiftinterface that needs Swift 6.3 or newer; the Command Line Tools that shipped with the first macOS 26 point releases include Swift 6.2.x, which cannot parse it. See issue #85.

pnpm build:swift now detects this mismatch and prints the same remediation, but if you hit it manually:

1. Install Xcode 26.x from the App Store (ships Swift 6.3+), or
2. Update Command Line Tools to a version that ships Swift 6.3+:

   softwareupdate --list
   sudo softwareupdate -i "Command Line Tools for Xcode-<latest>"
   

3. If both are installed, point xcode-select at the full Xcode:

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   

Verify with:

xcrun swiftc --version          # should report Apple Swift version 6.3 or newer
xcrun --show-sdk-version        # should match your macOS major version

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