Icloud MCP server

icloud-mcp

<!-- mcp-name: io.github.eodozzy/icloud-mcp -->

A Model Context Protocol server that gives AI assistants read-only access to your iCloud mail and calendar over IMAP and CalDAV. Credentials live in your OS keyring (macOS Keychain by default) — never in a config file or the repo.

Defaults target iCloud, but every endpoint is overridable, so it works against any standard IMAP/CalDAV provider.

Status

Read-only by default; writes are strictly opt-in. Mail, calendar, and contacts can be listed, searched, and read with no ability to change anything: the IMAP connection is opened read-only and bodies are fetched with BODY.PEEK[], so messages are never even marked as read.

Mutating tools span mail (sendmail, replymail, forwardmail), calendar (createevent, updateevent, deleteevent), and contacts (createcontact, updatecontact, deletecontact) — but all are disabled unless you set ICLOUDENABLEWRITES=1**, and even then every write requires an interactive confirmation (MCP elicitation) before it runs. See Writes (opt-in).

Writes (opt-in)

Mutations are gated two ways:

ICLOUDENABLEWRITES=1 is set in the server's environment.

1. Operator switch — write tools refuse with an explanatory error unless

to confirm the exact action before executing. Destructive operations (delete event / contact) are gated identically — no extra force flag, just the same confirmation.

1. Per-action confirmation — when enabled, each write tool calls back to the client

iCloud issues a single app-specific password covering IMAP, SMTP, CalDAV, and CardDAV — there is no scoped "write-only" credential — so write-safety is structural: mail is sent over a separate, fresh SMTP connection (the read path's IMAP client has no send capability), and the opt-in flag + confirmation guard every mutation.

Install

pip install icloud-mcp

Or run it without installing — handy for MCP clients that launch the server on demand:

uvx icloud-mcp

To install the latest unreleased code straight from GitHub:

pip install git+https://github.com/eodozzy/icloud-mcp

Or for local development:

git clone git@github.com:eodozzy/icloud-mcp
cd icloud-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[test]"

Requires Python 3.11+.

Credentials

Generate an app-specific password for your Apple ID (never use your main password), then store it in your keyring:

# macOS
security add-generic-password -a "you@icloud.com" -s "icloud-mcp" -w "xxxx-xxxx-xxxx-xxxx"

On other platforms, the cross-platform keyring library is used — keyring set icloud-mcp you@icloud.com also works anywhere.

The username comes from the ICLOUD_USERNAME environment variable. Resolution order for the password:

1. OS keyring (ICLOUDKEYRINGSERVICE, default icloud-mcp, + username)
2. ICLOUDAPPPASSWORD environment variable (fallback)

To reuse an existing keyring entry (e.g. one named my-icloud), set ICLOUDKEYRINGSERVICE=my-icloud.

Configuration

Set ICLOUD_USERNAME (required). All else is optional — see .env.example for the full list of endpoint/timezone overrides.

Register with an MCP client

The server speaks MCP over stdio: a client launches the icloud-mcp command as a subprocess and talks to it over stdin/stdout. "Installing" it into a client just means telling that client which command to run and which env vars to pass — the password itself stays in the keyring, never in the client config.

Shortened. The full README is on GitHub.