SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI officeicloud-mcp

icloud-mcp

Apple Mail, Calendar, Contacts, Reminders, Notes, Messages and Safari via AppleScript on macOS, or iCloud over IMAP, CalDAV and CardDAV elsewhere.

Open website

About this tool

Purpose

icloud-mcp is an MCP (Model Context Protocol) server used to let AI clients access Apple services. It covers seven services: Mail, Calendar, Contacts, Reminders, Notes, Messages, and Safari. According to the project description, it is currently the only MCP server that covers all seven of these services and provides two interchangeable backends.

Two Backend Modes

Local mode: Drives native macOS apps via AppleScript. No credentials required, no network access, and it can access services not exposed by iCloud protocols (Reminders, Notes, Messages, Safari).

Cloud mode: Uses IMAP/SMTP, CalDAV, and CardDAV protocols, and can run on any machine, not limited to a Mac. It covers only Mail, Calendar, and Contacts.

set-mode Tools can switch between the two modes at runtime without restarting.

Main Capabilities

The server exposes a total of 41 tools, divided by service:

  • General:about(returns server information, current mode, credential configuration status),check-auth-status(verifies credential availability for the current mode),set-mode(switches local/cloud).
  • Mail:list-emails、read-email、send-email、search-emails、mark-as-read、list-folders.
  • Calendar:list-events、create-event、update-event、delete-event、list-calendars.
  • Contacts:list-contacts、search-contacts、read-contact、create-contact、delete-contact、list-contact-accounts(local only),list-contact-groups(local only).
  • Reminders (local only):list-reminder-lists、list-reminders、create-reminder、update-reminder、complete-reminder、delete-reminder、search-reminders.
  • Notes (local only):list-note-folders、list-notes、read-note、create-note、search-notes.
  • Messages (local only):list-chats、read-messages、send-message、react-message. Reading requires the imsg CLI and Full Disk Access permission.
  • Safari (local only):list-safari-tabs、get-current-safari-url、open-safari-url、close-safari-tab.

Each tool has a typed schema, a human-readable title, and behavior annotations. All list-* tools return machine-readable structuredContent in addition to text output. Tools marked "local only" return an error in cloud mode, because iCloud protocols do not expose these services.

Access and Security Model

  • The server communicates only via JSON-RPC over stdin/stdout, opens no ports, and listens on no sockets.
  • Credentials are never logged.ICLOUD_APP_PASSWORD reads them once at startup and passes them only to IMAP/SMTP/CalDAV/CardDAV clients; diagnostic information prints only a fixed mask. Passwords can be placed in a .env file next to the module, or in the sensitive fields of the .mcpb package (stored by the host in the macOS keychain). Local mode has no passwords at all; macOS controls access through each app's automation authorization prompt, which can be revoked at any time.
  • Every tool parameter is validated by a zod schema before execution and type-coerced at AppleScript interpolation points.
  • The server does not collect or retain any data: no telemetry, no analytics, no on-disk state. Data flows only between the user's machine, the connected AI client, and Apple services. See PRIVACY.md for the full policy.

Tool Behavior Annotations

All list-*、read-*、search-*、get-* tools as well as about、check-auth-status are marked read-only. Nine tools have destructiveHint: four delete operations (delete-event、delete-contact、delete-reminder、close-safari-tab), three irreversible operations that reach others (send-email、send-message、react-message), and two in-place updates (update-event、update-reminder). Tools that reach the network or others have openWorldHint: all Mail and Calendar tools,send-message、react-message、open-safari-url. Read-only tools plus mark-as-read、complete-reminder、update-reminder、update-event、set-mode Marked as idempotent.

Usage

Requires Node.js 20 or higher.

Installation methods include:

  • Have an AI client (Claude, Claude Code, Cursor, ChatGPT, or any agent with shell/config access) install it automatically.
  • Add to claude_desktop_config.json. - Cloud mode requires adding credentials. - Desktop extension (.mcpb): Download from Releases .mcpb and open to sideload. The package will prompt you to choose a mode; in cloud mode, it stores the app-specific password in the macOS Keychain rather than a file.

Package manager support includes pnpm; the repository commits pnpm-lock.yaml.

Permissions and Troubleshooting

macOS Automation Prompts (Local Mode): The first time a tool accesses an app, macOS will ask whether to allow the calling program to control it. It asks once per app, not once per tool. You can approve in "System Settings → Privacy & Security → Automation" or grant it later. If you ignore the prompt, calls to that app will fail with an authorization error (osascript error -1743). macOS will not ask again on its own; you need to re-check the box or reset the decision (resetting clears automation permissions for all apps).

Full Disk Access (Reading Messages):list-chats and read-messages read the Messages database through the imsg CLI and are governed by Full Disk Access rather than Automation. You need to grant Full Disk Access in "System Settings → Privacy & Security → Full Disk Access" to the program that starts the server (Claude Desktop, Terminal, or your editor). If imsg is installed in a non-standard location, you can specify the path explicitly; the server looks in ICLOUD_MCP_IMSG_PATH、IMSG_PATH, the two Homebrew prefixes, and finally PATH.

Known Limitations

  • Large Mailboxes: The Mail.app tools iterate through messages via AppleScript, which is slow on very large mailboxes and may exceed the Apple Event timeout before returning. Use folder and a smaller count to narrow the request, or switch to cloud mode (IMAP filters server-side). This is an inherent property of the AppleScript bridge.
  • Large Calendar Sets: In local mode, list-events has the same AppleScript bottleneck. Date windows are already filtered within Calendar.app using whose queries, but it can still time out on accounts with many calendars (especially those subscribed to years of events such as holidays, sports events, or travel feeds).list-calendars and event-writing tools are unaffected. Until the planned EventKit backend lands, reading events is best done in cloud mode (CalDAV filters server-side and is fast at any scale).

App-Specific Password for Cloud Mode

Cloud mode requires an app-specific password. A regular Apple ID password will not work, and Apple only issues app-specific passwords for accounts with two-factor authentication enabled. Steps: sign in to appleid.apple.com; go to "Sign-In and Security → App-Specific Passwords"; generate and name one (e.g., "iCloud MCP"); put it together with ICLOUD_EMAIL into ICLOUD_APP_PASSWORD; if leaked, you can revoke it on the same page.

Environment Requirements

  • Node.js 20 or higher.
  • Local mode: macOS and the relevant apps installed; to read Messages, imsg and Full Disk Access are also required.
  • Cloud mode: any operating system, an iCloud account with two-factor authentication enabled, and an app-specific password. It only covers Mail, Calendar, and Contacts.

Environment variables are read from the environment or from the .env file next to the module; see .env.example. The test suite stubs osascript and the imsg CLI and does not touch real mail, calendar, or messages data, so it can run on any operating system.

License

MIT, see LICENSE.

Related tools

Browse category