iCloud MCP Server Apple
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| ICLOUD_EMAIL | No | Your iCloud address, required for cloud mode. | |
| USE_LOCAL_MODE | No | Set to 'false' to select cloud mode. Defaults to 'true' (local mode). | true |
| ICLOUD_APP_PASSWORD | No | App-specific password, required for cloud mode. | |
| ICLOUD_MCP_IMSG_PATH | No | Explicit path to the imsg binary. If unset, the server searches ICLOUD_MCP_IMSG_PATH, IMSG_PATH, Homebrew prefixes, and PATH. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Access to Apple services in two modes.
LOCAL (default, macOS only) drives the native apps via AppleScript. CLOUD uses the iCloud protocols and needs an app-specific password.
Reminders, Notes, Messages and Safari are LOCAL only: calling them in CLOUD mode returns an error. Use set-mode to switch without restarting.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| aboutA | Returns information about this iCloud MCP server |
| check-auth-statusA | Check if iCloud credentials are configured correctly |
| set-modeA | Switch between LOCAL (AppleScript/macOS apps) and CLOUD (iCloud protocols) modes |
| list-emailsA | Lists emails from a folder (default: inbox) |
| read-emailA | Reads the full content of an email by UID |
| send-emailA | Sends an email immediately from the user's account to one or more comma-separated recipients, with optional CC, BCC and HTML body. Cloud mode delivers over SMTP and returns the new message ID; local mode sends through Mail.app, which only sends plain text and returns no ID. There is no draft step, so the message goes out as soon as the tool runs. |
| search-emailsA | Searches one mail folder (inbox by default) by free text, sender, subject and unread state; the filters combine as AND. Results carry the same summary fields as list-emails, including the ref handle that read-email and mark-as-read take. |
| mark-as-readA | Marks an email as read or unread |
| list-foldersA | Lists all email folders |
| list-eventsA | Lists upcoming calendar events within a look-ahead window (30 days by default, up to 365). Each event carries its title, start and end times, and the ref handle that update-event and delete-event take as their eventUrl argument. |
| create-eventB | Creates a new calendar event |
| update-eventA | Updates an existing calendar event. Only the fields you pass are changed. In cloud mode the CalDAV property-merge preserves recurrence, invitees and alarms (experimental: the live round-trip is not yet verified). In local mode, every occurrence of a recurring event shares the series UID, so this acts on the whole series, not one occurrence. |
| delete-eventA | Deletes a calendar event. In local mode, every occurrence of a recurring event shares the series UID, so this acts on the whole series, not one occurrence. |
| list-calendarsA | Lists all available calendars |
| list-contactsA | Lists contacts from the user's address book, up to 50 per call, including the handle that read-contact and delete-contact take. For a targeted lookup, search-contacts filters by name, email or phone instead of paging through the full list. |
| search-contactsA | Search contacts by name, email, or phone |
| read-contactA | Get detailed information about a specific contact |
| create-contactA | Creates a contact in the user's address book (Contacts.app in local mode, iCloud over CardDAV in cloud mode). Every field is optional, so pass at least a name (displayName, or firstName and lastName) along with any known email, phone, organization, job title or notes. |
| delete-contactA | Permanently deletes a contact from the user's address book. Takes the handle returned by list-contacts or search-contacts; there is no undo through this server. |
| list-contact-accountsA | Lists all contact accounts (iCloud, Google, Exchange, etc.) - LOCAL mode only |
| list-contact-groupsA | Lists contact groups from all accounts or a specific account - LOCAL mode only |
| list-reminder-listsA | Lists all reminder lists from Reminders.app (LOCAL mode only) |
| list-remindersA | Lists reminders from a specific list or all lists (LOCAL mode only) |
| create-reminderA | Creates a new reminder (LOCAL mode only) |
| update-reminderB | Updates an existing reminder (LOCAL mode only) |
| complete-reminderA | Marks a reminder as complete or incomplete (LOCAL mode only) |
| delete-reminderA | Deletes a reminder (LOCAL mode only) |
| search-remindersA | Search reminders by text in name or body (LOCAL mode only) |
| list-note-foldersA | Lists all folders in Notes.app (LOCAL mode only) |
| list-notesA | Lists notes from a specific folder or all folders |
| read-noteA | Reads the content of a specific note |
| create-noteB | Creates a new note |
| search-notesA | Search notes by text in title or content |
| list-chatsA | List recent iMessage/SMS conversations, most recent first. Use |
| read-messagesA | Read message history for a specific iMessage/SMS conversation |
| send-messageA | Sends an iMessage or SMS to a phone number or email handle, with an optional file attachment. The message is delivered as soon as the tool runs; there is no draft step and no recall. |
| react-messageC | Send a tapback reaction (love, like, dislike, laugh, emphasis, question) |
| list-safari-tabsA | Lists all open tabs in Safari across all windows |
| get-current-safari-urlA | Gets the URL and title of the current/active Safari tab |
| open-safari-urlA | Opens a URL in Safari (new tab or new window) |
| close-safari-tabB | Closes a Safari tab |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 41 tools
Tools are organized around clearly distinct resources (mail, calendar, contacts, reminders, notes, messages, Safari) with action verbs that mostly separate them cleanly, e.g. list-contacts vs. search-contacts vs. read-contact. A few pairs need the descriptions to disambiguate: update-reminder vs. complete-reminder, and the meta tools about/check-auth-status/set-mode overlap slightly in purpose.
Nearly all 41 tools follow a consistent kebab-case verb_noun pattern (list-emails, create-event, delete-contact, search-notes). The exceptions are small: the bare noun 'about', the objectless 'mark-as-read', and 'set-mode'/'check-auth-status' which don't name a domain resource.
41 tools is heavy and well past the comfortable range, forcing the agent to scan a large surface to pick a tool. The breadth of seven Apple domains partly justifies it, but there are no aggregate/bulk tools and several near-siblings (three contact-list tools, two safari-tab getters) that inflate the count.
Mail, Calendar, Messages and Safari cover their core lifecycle, but there are notable holes: no update-contact, no update-note or delete-note, and no move/delete/reply for email. Reminders is complete only in LOCAL mode, so cloud-mode agents hit a hard wall there.