# Mcp Server Apple Events > MCP server providing native macOS integration with Apple Reminders and Calendar via EventKit - **Type:** MCP server - **Install:** `agentstack add mcp-fradser-mcp-server-apple-events` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [FradSer](https://agentstack.voostack.com/s/fradser) - **Installs:** 0 - **Category:** [Productivity](https://agentstack.voostack.com/c/productivity) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [FradSer](https://github.com/FradSer) - **Source:** https://github.com/FradSer/mcp-server-apple-events ## Install ```sh agentstack add mcp-fradser-mcp-server-apple-events ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Apple Events MCP Server [](https://x.com/FradSer) English | [简体中文](README.zh-CN.md) 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](https://github.com/FradSer/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`](https://github.com/FradSer/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: ```text Reminder permission denied. Unknown error ``` — even though running the same binary from Terminal works. See [issue #93](https://github.com/FradSer/mcp-server-apple-events/issues/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: ```bash # 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: ```bash 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** ```bash 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](https://github.com/FradSer/mcp-server-apple-events/issues/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+: ```bash softwareupdate --list sudo softwareupdate -i "Command Line Tools for Xcode-" ``` 3. If both are installed, point `xcode-select` at the full Xcode: ```bash sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer ``` Verify with: ```bash 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`: ```bash 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: ```json { "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: ```bash code ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` For Windows: ```bash 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)** ```json { "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 `dist/index.js`: ```json { "mcpServers": { "apple-reminders": { "command": "node", "args": ["/absolute/path/to/mcp-server-apple-events/dist/index.js"] } } } ``` For more information on connecting local MCP servers, see the [official MCP documentation](https://modelcontextprotocol.io/docs/develop/connect-local-servers). ### 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text 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 ```text Show me all my reminders. List all reminders in my "Shopping" list. Show my completed reminders. ``` ### Working with Lists ```text 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 Prompt Library The 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. - **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. - **smart-reminder-creator** — optional `task_idea` (a short description of what you want to do) generates an optimally scheduled reminder structure. - **reminder-review-assistant** — optional `review_focus` (e.g., overdue or a list name) to audit and optimize existing reminders. - **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. ### Design constraints and validation - Prompts are intentionally constrained to native Apple Reminders capabilities (no third-party automations) and ask for missing context before committing to irreversible actions. - Shared formatting keeps outputs renderable as Markdown sections or tables without extra parsing glue in client applications. - Run `pnpm test -- src/server/prompts.test.ts` to assert metadata, schema compatibility, and narrative assembly each time you amend prompt copy. ## Available MCP Tools This 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: ### Reminder Tasks Tool **Tool Name**: `reminders_tasks` Manages individ … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [FradSer](https://github.com/FradSer) - **Source:** [FradSer/mcp-server-apple-events](https://github.com/FradSer/mcp-server-apple-events) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-fradser-mcp-server-apple-events - Seller: https://agentstack.voostack.com/s/fradser - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.