Skip to content
Back to search

icloud-mcp

MCP server for Apple services — Mail, Calendar, Contacts, Reminders, Notes, Messages, Safari — via AppleScript (local) or iCloud IMAP/CalDAV/CardDAV (cloud)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/MrGo2/icloud-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/MrGo2/icloud-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrgo2--icloud-mcp/badge.svg)](/listings/mrgo2--icloud-mcp)

HTML

<a href="/listings/mrgo2--icloud-mcp"><img src="/api/listings/mrgo2--icloud-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 20 or newer.

Let your AI install it

Paste this into Claude, Claude Code, Cursor, ChatGPT or any agent with shell or config access:

Install the iCloud MCP server. It is the npm package "mcp-icloud" (Node 20+),
stdio transport, server name "icloud", command "npx" with args ["-y", "mcp-icloud"].
On Claude Code run: claude mcp add --transport stdio icloud -- npx -y mcp-icloud
For other clients, add that command/args pair to the client's MCP config file.
Local mode (default) needs macOS; cloud mode needs env vars USE_LOCAL_MODE=false,
ICLOUD_EMAIL and ICLOUD_APP_PASSWORD (app-specific password from account.apple.com).
Docs: https://github.com/MrGo2/icloud-mcp

Claude Desktop

Add to `claude_desktop_config.json`:

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"]
    }
  }
}

For cloud mode, add credentials:

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["-y", "mcp-icloud"],
      "env": {
        "USE_LOCAL_MODE": "false",
        "ICLOUD_EMAIL": "you@icloud.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio icloud -- npx -y mcp-icloud

VS Code

Use the badge at the top of this README, or add the same `command`/`args` pair to your MCP settings.

Desktop extension (.mcpb)

Download the `.mcpb` from [Releases](https://github.com/MrGo2/icloud-mcp/releases) and open it to sideload. The bundle prompts for the mode and, for cloud mode, stores the app-specific password in the macOS Keychain rather than a file.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 276 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
  3. <img src="assets/banner-light.svg" alt="icloud-mcp banner: Mail, Calendar, Contacts, Reminders, Notes, Messages and Safari for your AI assistant">
  4. </picture>
  5. <div align="center">
  6. [![npm](https://img.shields.io/npm/v/mcp-icloud?style=flat-square&color=cb3837&logo=npm)](https://www.npmjs.com/package/mcp-icloud)
  7. [![CI](https://github.com/MrGo2/icloud-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MrGo2/icloud-mcp/actions/workflows/ci.yml)
  8. [![Release](https://img.shields.io/github/v/release/MrGo2/icloud-mcp?style=flat-square&color=8250df)](https://github.com/MrGo2/icloud-mcp/releases/latest)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
  10. [![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen?style=flat-square&logo=node.js&logoColor=white)](package.json)
  11. [![MCP](https://img.shields.io/badge/MCP-SDK%20v2-a371f7?style=flat-square)](https://modelcontextprotocol.io)
  12. [![icloud-mcp MCP server](https://glama.ai/mcp/servers/MrGo2/icloud-mcp/badges/score.svg)](https://glama.ai/mcp/servers/MrGo2/icloud-mcp)
  13. [![Listed on PlugMCP](https://plugmcp.ai/api/badge/mrgo2-icloud-mcp.svg)](https://plugmcp.ai/mcp/mrgo2-icloud-mcp)
  14. </div>
  15. <img src="assets/demo.gif" alt="Claude creating a note, a reminder and a calendar event through icloud-mcp" width="100%">
  16. icloud-mcp covers seven Apple services with two interchangeable backends, and as far as we know it is the only MCP server that does. In local mode it drives the native macOS apps through AppleScript: no credentials, no network, and it reaches the services the iCloud protocols do not expose (Reminders, Notes, Messages, Safari). In cloud mode it speaks IMAP/SMTP, CalDAV and CardDAV instead, so it runs on any machine, not just a Mac. The `set-mode` tool switches between the two at runtime, without a restart.
  17. [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=icloud&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-icloud%22%5D%7D)
  18. [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=icloud&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1pY2xvdWQiXX0=)
  19. ## Features
  20. The server exposes 41 tools across Email, Calendar, Contacts, Reminders, Notes, Messages and Safari. Each tool carries a typed schema, a human title and behavioural annotations, and every `list-*` tool returns machine-readable `structuredContent` alongside its text output. Local mode needs no passwords at all; macOS privacy permissions take their place: Automation for the apps, plus one-time Calendars and Contacts prompts for `list-events` and the contact account/group tools, and Full Disk Access for reading messages.
  21. ## Access and security model
  22. The server speaks JSON-RPC over stdin/stdout only. It opens no ports and listens on no socket.
  23. Credentials are never logged. `ICLOUD_APP_PASSWORD` is read once at startup and handed only to the IMAP/SMTP/CalDAV/CardDAV clients; diagnostics print a fixed mask, never the value. Where you keep the password is up to you: a `.env` file beside the module for a manual install, or the `.mcpb` bundle's sensitive field, which the host stores in the macOS Keychain. Local mode has no password anywhere, since macOS gates access per app through its own Automation prompts, and you can revoke those at any time.
  24. Every tool argument is validated against a zod schema before the handler runs. Arguments are also coerced at each AppleScript interpolation site, so a value that is not a number cannot reach a script template.
  25. ## Privacy Policy
  26. The server collects nothing and keeps nothing: no telemetry, no analytics, no state on disk. Your data moves only between your machine, the AI client you connect and Apple's services. The full policy, covering collection, storage, third-party sharing, retention and contact, is in [PRIVACY.md](PRIVACY.md).
  27. ## Tools
  28. Tools marked local only return an error in cloud mode, because the iCloud protocols do not expose those services.
  29. ### Authentication
  30. - **about**
  31. - Returns information about this server, the active mode and whether credentials are configured
  32. - No input
  33. - **check-auth-status**
  34. - Verifies credentials are usable for the active mode
  35. - No input
  36. - **set-mode**
  37. - Switches between local and cloud without restarting
  38. - Input: `mode` (string, `local` or `cloud`)
  39. ### Email
  40. - **list-emails**: `folder` (string, optional), `count` (number, optional, max 50)
  41. - **read-email**: `uid` (string), `folder` (string, optional)
  42. - **send-email**: `to`, `subject`, `body` (strings); `cc`, `bcc` (strings, optional); `isHtml` (boolean, optional, cloud mode only)
  43. - **search-emails**: `query`, `from`, `subject`, `folder` (strings, optional), `unreadOnly` (boolean, optional), `count` (number, optional)
  44. - **mark-as-read**: `uid` (string), `folder` (string, optional), `isRead` (boolean, optional)
  45. - **list-folders**: no input
  46. ### Calendar
  47. - **list-events**: `count` (number, optional, max 50), `daysAhead` (number, optional)
  48. - **create-event**: `summary`, `start`, `end` (strings, ISO 8601); `description`, `location` (optional); `calendarUrl` (cloud) or `calendarName` (local)
  49. - **update-event**: `eventUrl` (string); any of `summary`, `start`, `end`, `description`, `location`. Only the fields you pass change
  50. - **delete-event**: `eventUrl` (string)
  51. - **list-calendars**: no input
  52. ### Contacts
  53. - **list-contacts**: `count` (number, optional, max 50)
  54. - **search-contacts**: `query` (string), `count` (number, optional). Matches name, organisation, email and phone; phone matching ignores formatting
  55. - **read-contact**: `contactUrl` (string)
  56. - **create-contact**: `displayName`, `firstName`, `lastName`, `email`, `phone`, `organization`, `title`, `notes` (all optional)
  57. - **delete-contact**: `contactUrl` (string)
  58. - **list-contact-accounts**: no input (local only). Returns each account's `id`, `name`, `type` (`cardDAV`, `exchange`, `local`) and `groupCount`
  59. - **list-contact-groups**: `accountId` (string, optional) (local only)
  60. ### Reminders (local only)
  61. - **list-reminder-lists**: no input
  62. - **list-reminders**: `listName` (string, optional), `includeCompleted` (boolean, optional), `count` (number, optional)
  63. - **create-reminder**: `name` (string); `body`, `dueDate`, `listName` (optional); `priority` (number 0-9, optional)
  64. - **update-reminder**: `reminderId` (string); any of `name`, `body`, `dueDate`, `priority`
  65. - **complete-reminder**: `reminderId` (string), `completed` (boolean, optional)
  66. - **delete-reminder**: `reminderId` (string)
  67. - **search-reminders**: `query` (string), `count` (number, optional)
  68. ### Notes (local only)
  69. - **list-note-folders**: no input
  70. - **list-notes**: `folderName` (string, optional), `count` (number, optional)
  71. - **read-note**: `noteId` (string)
  72. - **create-note**: `title` (string), `body` (string, optional), `folderName` (string, optional)
  73. - **search-notes**: `query` (string), `count` (number, optional)
  74. ### Messages (local only)
  75. Reading requires the [`imsg`](https://github.com/steipete/imsg) CLI and Full Disk Access.
  76. - **list-chats**: `limit` (number, optional, max 1000), `since` (ISO 8601, optional — only chats active since that date, e.g. a weekly review)
  77. - **read-messages**: `chatId` (number); `limit` (number, optional); `start`, `end` (ISO 8601, optional); `attachments` (boolean, optional)
  78. - **send-message**: `to` (string), `body` (string), `file` (string, optional)
  79. - **react-message**: `chatId` (number), `type` (`love`, `like`, `dislike`, `laugh`, `emphasis`, `question`)
  80. ### Safari (local only)
  81. - **list-safari-tabs**: no input
  82. - **get-current-safari-url**: no input
  83. - **open-safari-url**: `url` (string), `inNewWindow` (boolean, optional)
  84. - **close-safari-tab**: `windowIndex` (number, optional), `tabIndex` (number, optional)
  85. ### Tool annotations (MCP hints)
  86. Every tool declares its behaviour explicitly instead of relying on the spec defaults, which are deliberately pessimistic. All `list-*`, `read-*`, `search-*` and `get-*` tools, plus `about` and `check-auth-status`, are marked read-only. Nine tools carry `destructiveHint`: the four deletions (`delete-event`, `delete-contact`, `delete-reminder`, `close-safari-tab`), the three that reach another person irrevocably (`send-email`, `send-message`, `react-message`) and the two in-place updates (`update-event`, `update-reminder`). Tools that reach the network or another person carry `openWorldHint`: all Email and Calendar tools, `send-message`, `react-message` and `open-safari-url`. The read-only tools plus `mark-as-read`, `complete-reminder`, `update-reminder`, `update-event` and `set-mode` are marked idempotent.
  87. ## Installation
  88. Requires Node.js 20 or newer.
  89. ### Let your AI install it
  90. Paste this into Claude, Claude Code, Cursor, ChatGPT or any agent with shell or config access:
  91. ```
  92. Install the iCloud MCP server. It is the npm package "mcp-icloud" (Node 20+),
  93. stdio transport, server name "icloud", command "npx" with args ["-y", "mcp-icloud"].
  94. On Claude Code run: claude mcp add --transport stdio icloud -- npx -y mcp-icloud
  95. For other clients, add that command/args pair to the client's MCP config file.
  96. Local mode (default) needs macOS; cloud mode needs env vars USE_LOCAL_MODE=false,
  97. ICLOUD_EMAIL and ICLOUD_APP_PASSWORD (app-specific password from account.apple.com).
  98. Docs: https://github.com/MrGo2/icloud-mcp
  99. ```
  100. ### Claude Desktop
  101. Add to `claude_desktop_config.json`:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "icloud": {
  106. "command": "npx",
  107. "args": ["-y", "mcp-icloud"]
  108. }
  109. }
  110. }
  111. ```
  112. For cloud mode, add credentials:
  113. ```json
  114. {
  115. "mcpServers": {
  116. "icloud": {
  117. "command": "npx",
  118. "args": ["-y", "mcp-icloud"],
  119. "env": {
  120. "USE_LOCAL_MODE": "false",
  121. "ICLOUD_EMAIL": "you@icloud.com",
  122. "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
  123. }
  124. }
  125. }
  126. }
  127. ```
  128. ### Claude Code
  129. ```bash
  130. claude mcp add --transport stdio icloud -- npx -y mcp-icloud
  131. ```
  132. ### VS Code
  133. Use the badge at the top of this README, or add the same `command`/`args` pair to your MCP settings.
  134. ### Desktop extension (.mcpb)
  135. Download the `.mcpb` from [Releases](https://github.com/MrGo2/icloud-mcp/releases) and open it to sideload. The bundle prompts for the mode and, for cloud mode, stores the app-specific password in the macOS Keychain rather than a file.
  136. ## Permissions and troubleshooting
  137. ### macOS Automation prompts (local mode)
  138. The first time a tool touches an app, macOS asks whether the calling program may control it. This happens once per app, not once per tool. Approve the prompt, or grant it later under **System Settings → Privacy & Security → Automation**.
  139. If you dismissed a prompt, calls to that app fail with an authorisation error (`osascript` error `-1743`, "not authorized to send Apple events"). macOS will not ask again on its own. Re-enable the checkbox under Automation, or reset the decisions:
  140. ```bash
  141. tccutil reset AppleEvents
  142. ```
  143. That clears Automation permissions for every app, so expect the prompts to return on next use.
  144. ### Contacts access (accounts and groups)
  145. `list-contact-accounts` and `list-contact-groups` read accounts and groups through the macOS Contacts framework, because Contacts.app's scripting interface has no notion of accounts. The first call asks the program that launches the server for access to your contacts. Approve it once, or grant it later under **System Settings → Privacy & Security → Contacts**.
  146. ### Full Disk Access (reading messages)
  147. `list-chats` and `read-messages` read the Messages database through the `imsg` CLI, which is gated by Full Disk Access, not Automation. Grant it to the program that launches the server (Claude Desktop, your terminal, or your editor) under **System Settings → Privacy & Security → Full Disk Access**. Without it, those tools report that Full Disk Access is required.
  148. If `imsg` is installed somewhere unusual, point at it explicitly:
  149. ```bash
  150. export ICLOUD_MCP_IMSG_PATH=/opt/homebrew/bin/imsg
  151. ```
  152. The server otherwise looks in `ICLOUD_MCP_IMSG_PATH`, `IMSG_PATH`, both Homebrew prefixes, and finally `PATH`.
  153. ### Known limitation: large mailboxes
  154. Mail.app tools iterate messages through AppleScript, which is slow on very large mailboxes and can exceed the Apple Event timeout before returning. Narrow the request with `folder` and a smaller `count`, or use cloud mode, where IMAP does the filtering server-side. This is a property of the AppleScript bridge, not something the server can work around.
  155. ### Calendar access (local mode)
  156. `list-events` in local mode no longer scripts Calendar.app when it can avoid it. It reads the date window straight from EventKit, the macOS calendar store, in one query that returns in about a tenth of a second even with dozens of subscribed calendars. EventKit needs its own permission, separate from Automation: the first `list-events` call asks the program that launches the server (Claude Desktop, your terminal, or your editor) for access to your calendars. Approve it once, or grant it later under **System Settings → Privacy & Security → Calendars**.
  157. If that access is denied, restricted or left unanswered, `list-events` falls back to the old Calendar.app query and logs `EventKit unavailable` on stderr. That path still filters the window inside Calendar.app with a `whose` query, but on accounts with many calendars, especially subscribed ones carrying years of events (holidays, sports fixtures, travel feeds), it can exceed any reasonable timeout. In that case grant Calendars access, or use cloud mode, where CalDAV filters server-side (see [#11](https://github.com/MrGo2/icloud-mcp/issues/11)).
  158. Through EventKit, a recurring event appears once per occurrence in the window, and every occurrence carries the series id. Passing that id to `update-event` or `delete-event` in local mode changes or deletes the whole series.
  159. ### App-specific password (cloud mode)
  160. Cloud mode needs an app-specific password. Your normal Apple ID password will not work, and Apple only issues app-specific passwords on accounts with two-factor authentication turned on.
  161. 1. Sign in at [appleid.apple.com](https://appleid.apple.com).
  162. 2. Go to **Sign-In and Security → App-Specific Passwords**.
  163. 3. Generate one and name it, for example, "iCloud MCP".
  164. 4. Put it in `ICLOUD_APP_PASSWORD`, together with `ICLOUD_EMAIL`.
  165. Revoke it from the same page if it is ever exposed.
  166. ### Checking what the server thinks
  167. Call `about` for the active mode and service list, and `check-auth-status` to confirm credentials are usable in the current mode.
  168. ## Requirements
  169. - Node.js 20 or newer
  170. - Local mode: macOS with the relevant apps installed, plus `imsg` and Full Disk Access if you want to read messages
  171. - Cloud mode: any OS, an iCloud account with two-factor authentication, and an app-specific password. Covers Email, Calendar and Contacts only
  172. ## Configuration
  173. | Variable | Default | Purpose |
  174. |---|---|---|
  175. | `USE_LOCAL_MODE` | `true` | `false` selects cloud mode |
  176. | `ICLOUD_EMAIL` | (unset) | iCloud address, cloud mode only |
  177. | `ICLOUD_APP_PASSWORD` | (unset) | App-specific password, cloud mode only |
  178. | `ICLOUD_MCP_IMSG_PATH` | (unset) | Explicit path to the `imsg` binary |
  179. Read from the environment, or from a `.env` file beside the module. See `.env.example`.
  180. ## Development
  181. `pnpm` is the supported package manager; `pnpm-lock.yaml` is the committed lockfile.
  182. ```bash
  183. pnpm install
  184. pnpm test # unit + contract suites, and a live stdio session
  185. pnpm run inspect # drive the server with the MCP Inspector
  186. ```
  187. The test suites stub `osascript` and the `imsg` CLI, so they touch no real mail, calendar or message data. They need macOS, because local mode refuses to start elsewhere; CI runs them on a macOS runner.
  188. ## License
  189. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.