apple-mcp

Implements a Model Context Protocol server that discovers and exposes Apple application functionality as standardized MCP tools through a dual-mode initialization strategy. The server uses eager and lazy module loading to manage eight distinct Apple application integrations (Notes, Mail, Messages, Calendar, Contacts, Reminders, Maps, Web Search), allowing MCP-compatible clients like Claude Desktop and Cursor IDE to discover and invoke these tools through a unified interface without direct AppleScript knowledge.

Executes automation commands against macOS applications by translating MCP tool calls into AppleScript (via run-applescript) or JavaScript for Automation (JXA via @jxa/run library). The system uses a hybrid approach where some applications (Messages, Mail) use AppleScript for reliability, while others (Notes, Contacts, Reminders, Calendar, Maps) use JXA for better performance and modern JavaScript syntax support. Each tool invocation is wrapped with error handling and safe mode checks to prevent unintended application state changes.

Implements a safety layer that validates automation operations before execution and provides detailed error context from AppleScript/JXA failures. Includes checks for invalid parameters (malformed email addresses, invalid dates), application state validation (checking if app is running), and graceful error recovery with diagnostic information. Errors include stack traces from automation runtime and suggestions for resolution, enabling developers to debug automation failures without direct AppleScript knowledge.

Supports composition of multiple automation operations into single natural language requests through sequential tool invocation and data threading. Enables workflows like 'read notes, find contacts, send messages' where output from one operation feeds into the next without intermediate user interaction. The MCP server handles tool sequencing, data transformation between tools, and error propagation across the workflow. Allows AI clients to express complex multi-application workflows as single requests.

Translates natural language requests into structured operations against Apple Notes through JXA automation. Supports listing all notes with metadata, searching notes by content or title, reading full note content with formatting, and creating new notes with specified content. The implementation uses @jxa/run to execute JavaScript directly in the Notes application context, providing access to note objects, folders, and metadata without requiring AppleScript syntax translation.

Provides hybrid AppleScript/JXA-based email automation for Mail application, supporting message composition and sending, inbox/folder searching with query syntax, scheduled delivery (send at specific time), and message metadata retrieval. Uses AppleScript for reliability on send operations and JXA for search performance, with support for attachments, CC/BCC recipients, and HTML content. Integrates with Mail's native search indexing for fast query execution across large mailboxes.

Enables sending iMessage and SMS messages through Messages application via AppleScript automation, and reading conversation history from specific contacts or group chats. Supports both text messages and rich content (emojis, formatting), with access to message timestamps, sender information, and conversation metadata. Uses AppleScript for reliability and direct application control, with error handling for invalid phone numbers/email addresses and network failures.

Implements JXA-based calendar automation supporting event search by date range or keyword, creation of new calendar events with attendees and reminders, and retrieval of event details (time, location, attendees, notes). Supports natural language date parsing (e.g., 'next Tuesday', 'in 2 weeks') through client-side interpretation, with automatic timezone handling and conflict detection. Events are created in the default calendar or specified calendar with full iCal property support.

Provides JXA-based contact management supporting full-text search across contact names, email addresses, and phone numbers, with retrieval of contact details (name, phone, email, organization, address). Search results include all contact information fields, enabling AI agents to disambiguate between similarly-named contacts and retrieve complete contact records for communication workflows. Supports fuzzy matching for name searches and returns contact metadata for further processing.

Enables JXA-based reminder management supporting creation of new reminders with due dates, priority levels, and notes, as well as searching and listing reminders by status (completed/pending) or due date range. Supports both calendar-based reminders (with specific times) and all-day reminders, with automatic timezone handling. Reminders are created in the default Reminders list or specified list, with full support for reminder metadata (completion status, priority, notes).

Implements JXA-based Maps integration supporting location search by address or landmark name, retrieval of location coordinates and metadata (address, phone, website), and directions generation between two locations with route details (distance, estimated time, turn-by-turn steps). Supports multiple route types (driving, walking, transit) with automatic selection based on context. Results include map URLs for opening locations in Maps application.

Provides HTTP-based web search integration using DuckDuckGo API, supporting keyword search with result ranking and content snippet retrieval. Returns search results with title, URL, and preview text without requiring API keys or authentication. Enables AI agents to augment responses with current web information and fact-checking capabilities. Results are ranked by relevance and include domain information for source credibility assessment.