Apple Events MCP Server

English | 简体中文

A Model Context Protocol (MCP) server providing native integration with Apple Reminders and Calendar on macOS via the EventKit framework. Exposes reminders, lists, subtasks, and calendar events through a standardized interface with full CRUD operations.

The EventKit backend is the standalone event Swift CLI, vendored as a git submodule and built into bin/event during pnpm install — no separate brew install required. See docs/migration-to-event-cli.md for the v1.5.0 backend swap and the list of write fields not yet exposed by event.

Table of Contents

• Features
• Prerequisites
• Quick Start
• Configuration
• macOS Permissions
• Usage Examples
• Write confirmation and untrusted data
• Available MCP Tools
• Structured Prompt Library
• Development
• License
• Contributing

Features

• Full CRUD for reminders, subtasks, reminder lists, and calendar events
• Priority (high/medium/low/none), tags, and checklist subtasks with progress tracking
• Multi-criteria filtering: completion, due-date range, priority, tags, full-text search, recurring, location-based
• Flexible date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm:ss, ISO 8601) with timezone awareness
• Native macOS integration via EventKit — values configured in Reminders.app / Calendar.app round-trip through read responses
• Automatic macOS permission discovery and prompting
• Full Unicode support with comprehensive input validation

Prerequisites

• Node.js 20 or later
• macOS (required for EventKit)
• Xcode Command Line Tools (only when building from source)
• pnpm (recommended)

The published npm package ships a pre-built, universal, code-signed bin/event binary, so npx users need neither Xcode nor a Swift toolchain. Building from a git clone requires the items above.

Quick Start

npx mcp-server-apple-events

Configuration

Add the server to your MCP client. The npx form works for every client below; for a local build, replace command/args with node pointing at dist/index.js.

Cursor

Settings → MCP → Add new global MCP server:

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

ChatWise

Settings → Tools → "+", then:

• Type: stdio
• ID: apple-reminders
• Command: mcp-server-apple-events
• Args: (empty)

Claude Desktop

Edit claude_desktop_config.json (open it via Settings → Developer Option → Edit Config, or directly at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS / %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

For a local build:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-apple-events/dist/index.js"]
    }
  }
}

See the official MCP docs for connecting local servers. Restart Claude Desktop completely (quit, not just close) for changes to take effect.

macOS Permissions

The server launches the vendored event CLI directly. macOS retains its normal attribution to the application that launched the server, so authorize that host under System Settings > Privacy & Security > Reminders / Calendars. Each host needs its own approval; a grant made from a terminal does not authorize a separate desktop MCP client.

The host must support EventKit permission requests and declare the required usage descriptions. If it does not, macOS may deny access without showing a prompt. Use a host that supports these permissions. The server does not bypass this restriction by making a public helper self-responsible: doing so would let unrelated local processes reuse that helper's Calendar and Reminders grant.

When event detects a notDetermined status it calls requestFullAccessToReminders / requestFullAccessToEvents. Run ./check-permissions.sh from the same host context to diagnose access; running it in a terminal checks that terminal's permissions only. Usage descriptions are required for protected resources; see Apple's app distribution guidance.

Calendar read errors or missing prompts

For Failed to read calendar events, enable Full Calendar Access for the calling application under System Settings > Privacy & Security > Calendars. If no prompt appears, check that the host supports EventKit permissions and declares the usage descriptions, then restart it and retry. AppleScript Automation approval is separate from EventKit Calendar and Reminders approval.

Upgrading from the responsibility-disclaim helper

Reinstall the package to remove the old bin/event-disclaim artifact. For a source checkout, remove that generated file before rebuilding. Revoke the old event grant in System Settings > Privacy & Security > Reminders / Calendars, then authorize each host you intend to use. Updating the server cannot revoke existing macOS grants or remove older copies installed elsewhere.

Headless / launchd runs hang instead of failing

When the server runs from a context with no GUI session (SSH, launchd agent/daemon), the first EventKit call can block forever waiting on a permission prompt that can never be rendered — the MCP request never settles and a child process leaks per call. The server now kills any event call that exceeds 30 s (SIGKILL) and returns a readable error instead. Tune it with the EVENTKIT_CLI_TIMEOUT_MS environment variable (milliseconds; invalid/zero values fall back to the default — the timeout cannot be disabled, though huge values up to 2^31-1 ms are accepted). The vendored event CLI (pinned via FradSer/event#15) additionally fails fast when no GUI session exists and gives up on an unanswerable prompt after 15 s (EVENT_PERMISSION_TIMEOUT_MS), reporting Permission denied: Timed out waiting for ... so the host can show a permission-specific message before the server's kill fires (15 s < 30 s). See issue #113.

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

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 — it needs Swift 6.3 or newer, but the Command Line Tools shipped with early macOS 26 point releases include Swift 6.2.x. pnpm build:event detects this and prints the same remediation; see issue #85. Fix by installing Xcode 26.x from the App Store, or updating Command Line Tools to a Swift 6.3+ version:

softwareupdate --list
sudo softwareupdate -i "Command Line Tools for Xcode-<latest>"
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer   # if full Xcode is installed
xcrun swiftc --version    # should report Apple Swift version 6.3 or newer

Usage Examples

Once configured, ask Claude to interact with your Apple Reminders and Calendar. Example prompts:

Create a reminder to "Buy groceries" for tomorrow at 5 PM with tags shopping and errands.
Add a high-priority reminder to "Finish quarterly report" due Friday in my "Work" list.
Create "Grocery shopping" with subtasks: milk, eggs, bread, butter.
Show me all high-priority reminders due today tagged "urgent".
Show subtasks for my "Grocery shopping" reminder and mark "milk" as complete.
Update "Buy groceries" — change the title to "Buy organic groceries" and set priority to high.
Show reminders from my "Work" list, and list all my reminder lists.
Create a calendar event "Team standup" tomorrow from 9:00 to 9:30 in "Work".
Show my calendar events for the next week.
Invite alex@example.com to my "Team standup" event.
Cancel just the September 21 occurrence of my weekly "Team standup".

The server processes natural-language requests, interacts with Apple's native Reminders and Calendar apps, and returns structured results.

Alarms, recurrence rules, and location triggers are read-only via this server — configure them in Reminders.app / Calendar.app. Read tools preserve these values in structured records when the underlying app provides them.

Write confirmation and untrusted data

Server write confirmation is off by default. Clients without MCP form elicitation can write. Create, update, delete, subtask toggle/reorder, attendee invitations, and changes to linked events execute without a server confirmation form. Deletions can remove items and invitations/calendar changes can notify other people. This changes the v1.6.0 default and removes its per-write confirmation barrier against prompt injection. Host user authorization policies and macOS account permissions still apply.

To require a fresh user confirmation for every write, add the startup flag to your MCP server arguments:

{
  "command": "npx",
  "args": ["-y", "mcp-server-apple-events", "--require-write-confirmation"]
}

For a local build, use node dist/index.js --require-write-confirmation. Omit the flag to use the default. The flag takes no value and has no negate