icloud-mcp

An MCP server for iCloud Calendar, Contacts, and Mail — usable from any MCP-capable AI client (Claude Desktop, Claude Code, Cursor, Windsurf, etc.).

Only uses Apple's officially documented protocols: CalDAV (calendar), CardDAV (contacts), and IMAP/SMTP (mail). It does not touch Reminders, Notes, Find My, or Photos — those only have an undocumented, reverse-engineered API that's out of scope here (see Scope below).

Status

Early development. Not yet published to npm — see Development to run it from source in the meantime.

Tools

Tool	Read/Write	Description
health_check	read	Confirms the server is running
list_calendars	read	Lists iCloud calendars
list_events	read	Lists events in a calendar within a time range
get_event	read	Fetches a single event
create_event	write	Creates a calendar event
update_event	write	Updates an existing event
delete_event	write	Deletes an event
list_contacts	read	Lists contacts, optionally filtered
search_contacts	read	Searches contacts by name/org/email/phone
get_contact	read	Fetches a single contact
create_contact	write	Creates a contact
update_contact	write	Updates an existing contact
delete_contact	write	Deletes a contact
list_mailboxes	read	Lists IMAP mailboxes/folders
list_messages	read	Lists recent messages in a mailbox
search_messages	read	Searches messages by sender/subject/text
get_message	read	Fetches a single message's headers + text body
send_message	write	Sends an email

Write tools are disabled by default. They only register when ICLOUD_MCP_ALLOW_WRITE=true is set — see Security.

Setup

1. Generate an app-specific password

Apple requires a dedicated app-specific password for third-party CalDAV/CardDAV/IMAP access — never use your actual Apple ID password here.

1. Go to appleid.apple.com → Sign-In and Security → App-Specific Passwords
2. Generate one (e.g. named "icloud-mcp") and copy it

2. Configure environment variables

Variable	Required	Description
ICLOUD_APPLE_ID	yes	Your Apple ID email
ICLOUD_APP_SPECIFIC_PASSWORD	yes*	The app-specific password from step 1
ICLOUD_MCP_ALLOW_WRITE	no	Set to true to enable write tools (default: read-only)
ICLOUD_CALDAV_URL	no	Override the CalDAV endpoint (default: https://caldav.icloud.com)
ICLOUD_CARDDAV_URL	no	Override the CardDAV endpoint (default: https://contacts.icloud.com)

* Instead of ICLOUD_APP_SPECIFIC_PASSWORD, you can store the password in your OS keychain under service icloud-mcp, account <your Apple ID> (macOS Keychain / libsecret via keytar), and omit the env var.

3. Add it to your MCP client

Once published, the server runs via npx @lejangt/icloud-mcp over stdio.

Claude Code:

claude mcp add icloud --env ICLOUD_APPLE_ID=you@icloud.com --env ICLOUD_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx -- npx @lejangt/icloud-mcp

Claude Desktop / Cursor / Windsurf / any client using mcpServers JSON config:

{
  "mcpServers": {
    "icloud": {
      "command": "npx",
      "args": ["@lejangt/icloud-mcp"],
      "env": {
        "ICLOUD_APPLE_ID": "you@icloud.com",
        "ICLOUD_APP_SPECIFIC_PASSWORD": "xxxx-xxxx-xxxx-xxxx"
      }
    }
  }
}

Add "ICLOUD_MCP_ALLOW_WRITE": "true" to env if you want write tools enabled.

Security

• Write tools are opt-in. Without ICLOUD_MCP_ALLOW_WRITE=true, the server only exposes read tools — reducing the blast radius if a client misbehaves or credentials leak.
• Enabling write tools means the AI agent can send email and modify/delete calendar events and contacts on your behalf. Only enable it if you understand and accept that.
• All connections use TLS; credentials are never logged (see src/logging.ts).
• See SECURITY.md for the full threat model and how to report vulnerabilities.

Scope

Calendar, contacts, and mail are supported because Apple documents stable, official protocols for them (CalDAV/CardDAV/IMAP+SMTP with an app-specific password). Reminders, Notes, Find My, and Photos are intentionally out of scope: the only way to access them programmatically is Apple's undocumented, reverse-engineered iCloud web API (as used by projects like pyicloud), which requires your full Apple ID session (2FA included) and can break without warning when Apple changes internals. That's a meaningfully different risk/maintenance profile and isn't part of this project.

Development

Requires Node.js ≥ 18.

npm install
npm run build      # compile TypeScript to dist/
npm run dev        # watch mode
npm run lint
npm run typecheck
npm test

Run the server directly against real credentials for manual testing:

ICLOUD_APPLE_ID=you@icloud.com ICLOUD_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx node dist/index.js

Or drive it interactively with the MCP Inspector:

ICLOUD_APPLE_ID=you@icloud.com ICLOUD_APP_SPECIFIC_PASSWORD=xxxx-xxxx-xxxx-xxxx \
  npx @modelcontextprotocol/inspector node dist/index.js

License

MIT — see LICENSE.