# icloud-mcp [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/MrGo2/icloud-mcp  
**GitHub Stars:** 79  
**npm Downloads (last month):** 3730  
**Views:** 12  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/icloud-mcp

## Description
Apple Mail, Calendar, Contacts, Reminders, Notes, Messages and Safari via AppleScript or iCloud

## Tools
Capabilities this server exposes over MCP:

- **about** — Returns information about this iCloud MCP server
- **check-auth-status** — Check if iCloud credentials are configured correctly
- **set-mode** — Switch between LOCAL (AppleScript/macOS apps) and CLOUD (iCloud protocols) modes
- **list-emails** — Lists emails from a folder (default: inbox)
- **read-email** — Reads the full content of an email by UID
- **send-email** — 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-emails** — 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-read** — Marks an email as read or unread
- **list-folders** — Lists all email folders
- **list-events** — 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-event** — Creates a new calendar event
- **update-event** — 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).
- **delete-event** — Deletes a calendar event
- **list-calendars** — Lists all available calendars
- **list-contacts** — 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-contacts** — Search contacts by name, email, or phone
- **read-contact** — Get detailed information about a specific contact
- **create-contact** — 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-contact** — 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-accounts** — Lists all contact accounts (iCloud, Google, Exchange, etc.) - LOCAL mode only
- **list-contact-groups** — Lists contact groups from all accounts or a specific account - LOCAL mode only
- **list-reminder-lists** — Lists all reminder lists from Reminders.app (LOCAL mode only)
- **list-reminders** — Lists reminders from a specific list or all lists (LOCAL mode only)
- **create-reminder** — Creates a new reminder (LOCAL mode only)
- **update-reminder** — Updates an existing reminder (LOCAL mode only)
- **complete-reminder** — Marks a reminder as complete or incomplete (LOCAL mode only)
- **delete-reminder** — Deletes a reminder (LOCAL mode only)
- **search-reminders** — Search reminders by text in name or body (LOCAL mode only)
- **list-note-folders** — Lists all folders in Notes.app (LOCAL mode only)
- **list-notes** — Lists notes from a specific folder or all folders
- **read-note** — Reads the content of a specific note
- **create-note** — Creates a new note
- **search-notes** — Search notes by text in title or content
- **list-chats** — List recent iMessage/SMS conversations with contact names and last message preview
- **read-messages** — Read message history for a specific iMessage/SMS conversation
- **send-message** — 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-message** — Send a tapback reaction (love, like, dislike, laugh, emphasis, question)
- **list-safari-tabs** — Lists all open tabs in Safari across all windows
- **get-current-safari-url** — Gets the URL and title of the current/active Safari tab
- **open-safari-url** — Opens a URL in Safari (new tab or new window)
- **close-safari-tab** — Closes a Safari tab

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "icloud-mcp": {
    "command": "npx",
    "args": ["-y","mcp-icloud"],
    "env": {
      "ICLOUD_APP_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `ICLOUD_APP_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What icloud-mcp does

icloud-mcp exposes Apple productivity and communication services as MCP tools. It covers email, calendars, contacts, reminders, notes, Messages, and Safari. Read, search, create, update, complete, delete, send, and navigation operations are available according to the service and active backend.

The server supports two operating modes. LOCAL mode controls native macOS applications through AppleScript and does not require an iCloud password. CLOUD mode uses iCloud-compatible IMAP and SMTP for mail, CalDAV for calendars, and CardDAV for contacts, allowing operation on machines that are not Macs. Services unavailable through those protocols, including Reminders, Notes, Messages, and Safari, are local-only.

## How it works

Communication uses JSON-RPC over standard input and output. The server does not open a port or listen on a socket. The set-mode tool changes between LOCAL and CLOUD during runtime.

Email tools can list folders, retrieve and search messages, change read state, and send mail. Sending is immediate rather than draft-based. Cloud delivery can include an HTML body and returns a message ID; local Mail.app delivery is plain text and does not return one.

Calendar tools list calendars and upcoming events, create events, update selected fields, and delete events. Contact tools support lookup, detailed reads, creation, and permanent deletion. Reminders, Notes, Messages, and Safari tools are available through local macOS applications, with Messages reading requiring the imsg command-line tool and Full Disk Access.

## Setup and configuration

Node.js 20 or newer is required. Install the npm package with an MCP client using the command `npx -y mcp-icloud`.

Cloud mode uses the `ICLOUD_APP_PASSWORD` environment variable. Credentials are read at startup and passed to the relevant mail and iCloud protocol clients; diagnostics mask the password. A local installation can load the value from a `.env` file, while the macOS bundle can store it in its sensitive configuration field.

LOCAL mode requires macOS privacy permissions. Automation access is needed for the controlled apps, Calendar and Contacts permissions are used by specific calendar and contact operations, and Full Disk Access is required for reading Messages. Use about and check-auth-status to inspect the active mode and authentication state.

## Tools and capabilities

- Inspect server information and authentication status.
- Switch between local AppleScript and cloud protocol backends.
- List, read, search, send, and mark email; enumerate mail folders.
- List, create, update, and delete calendar events and calendars.
- Search, read, create, and permanently delete contacts; inspect local accounts and groups.
- Manage local reminder lists and reminders, including completion state.
- List, read, search, and create local Notes content.
- List chats, read and send Messages, and add message reactions locally.
- List Safari tabs, retrieve the current URL, open URLs, and close tabs.

Tool arguments are validated before execution. List operations also return structured machine-readable content alongside text output.

## Limitations and notes

Operations marked local-only return an error in CLOUD mode. Cloud calendar updates merge only the fields supplied, while preserving other CalDAV properties; recurrence, invitees, and alarms have an experimental round-trip status.

Deletion is permanent through this server for contacts, reminders, events, and Safari tabs. Email and Messages are sent immediately when their send tools run. macOS permissions and the imsg dependency determine whether local features can access the underlying applications and data.

The server states that it collects no telemetry, analytics, or persistent local state. Data moves between the machine, the connected AI client, and Apple services.

_Full upstream README: https://allmcps.com/mcp/icloud-mcp/readme_