MrGo2/icloud-mcp

Features
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 Automation permissions take their place.
Access and security model
The server speaks JSON-RPC over stdin/stdout only. It opens no ports and listens on no socket.
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.
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.
Privacy Policy
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.
Tools
Tools marked local only return an error in cloud mode, because the iCloud protocols do not expose those services.
Authentication
- **about**
- Returns information about this server, the active mode and whether credentials are configured
- No input
- **check-auth-status**
- Verifies credentials are usable for the active mode
- No input
- **set-mode**
- Switches between local and cloud without restarting
- Input: mode (string, local or cloud)
Email
- **list-emails**: folder (string, optional), count (number, optional, max 50)
- **read-email**: uid (string), folder (string, optional)
- **send-email**: to, subject, body (strings); cc, bcc (strings, optional); isHtml (boolean, optional, cloud mode only)
- **search-emails**: query, from, subject, folder (strings, optional), unreadOnly (boolean, optional), count (number, optional)
- **mark-as-read**: uid (string), folder (string, optional), isRead (boolean, optional)
- **list-folders**: no input
Calendar
- **list-events**: count (number, optional, max 50), daysAhead (number, optional)
- **create-event**: summary, start, end (strings, ISO 8601); description, location (optional); calendarUrl (cloud) or calendarName (local)
- **update-event**: eventUrl (string); any of summary, start, end, description, location. Only the fields you pass change
- **delete-event**: eventUrl (string)
- **list-calendars**: no input
Contacts
- **list-contacts**: count (number, optional, max 50)
- **search-contacts**: query (string), count (number, optional). Matches name, organisation, email and phone; phone matching ignores formatting
- **read-contact**: contactUrl (string)
- **create-contact**: displayName, firstName, lastName, email, phone, organization, title, notes (all optional)
- **delete-contact**: contactUrl (string)
- **list-contact-accounts**: no input (local only)
- **list-contact-groups**: accountId (string, optional) (local only)
Reminders (local only)
- **list-reminder-lists**: no input
- **list-reminders**: listName (string, optional), includeCompleted (boolean, optional), count (number, optional)
- **create-reminder**: name (string); body, dueDate, listName (optional); priority (number 0-9, optional)
- **update-reminder**: reminderId (string); any of name, body, dueDate, priority