FradSer/mcp-server-apple-events

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
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:
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):
For a local build:
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