io.github.eodozzy/icloud-mcp

Official

by eodozzy · Python

Read-only-by-default MCP server for iCloud mail, calendar, and contacts (IMAP/CalDAV/CardDAV).

Read-only access to iCloud mail, calendar, and contacts.

Topics

caldavcalendarcarddavclaudeemailicloudimapmcpmodel-context-protocolllm-tools

README.md9 KBView on GitHub

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 (send_mail, reply_mail, forward_mail), calendar (create_event, update_event, delete_event), and contacts (create_contact, update_contact, delete_contact) — but all are disabled unless you set ICLOUD_ENABLE_WRITES=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:

Operator switch — write tools refuse with an explanatory error unless ICLOUD_ENABLE_WRITES=1 is set in the server's environment.
Per-action confirmation — when enabled, each write tool calls back to the client to confirm the exact action before executing. Destructive operations (delete event / contact) are gated identically — no extra force flag, just the same confirmation.

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

bash

pip install icloud-mcp

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

bash

uvx icloud-mcp

To install the latest unreleased code straight from GitHub:

bash

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

Or for local development:

bash

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:

bash

# 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:

OS keyring (ICLOUD_KEYRING_SERVICE, default icloud-mcp, + username)
ICLOUD_APP_PASSWORD environment variable (fallback)

To reuse an existing keyring entry (e.g. one named my-icloud), set ICLOUD_KEYRING_SERVICE=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.

If icloud-mcp isn't on your PATH (e.g. you installed into a virtualenv), use the absolute path to the launcher, e.g. /path/to/repo/.venv/bin/icloud-mcp.

Claude Code

bash

claude mcp add icloud \
  --env ICLOUD_USERNAME=you@icloud.com \
  --env ICLOUD_KEYRING_SERVICE=icloud-mcp \
  -- icloud-mcp

Then claude mcp list to confirm. Add -s user to make it available across all projects rather than just the current one.

Claude Desktop

Add the server to Claude Desktop's config file. On macOS this is:

code

~/Library/Application Support/Claude/claude_desktop_config.json

(On Windows: %APPDATA%\Claude\claude_desktop_config.json.)

The easiest way to open it is Settings → Developer → Edit Config. Add an mcpServers key alongside whatever is already in the file — do not paste a second top-level { ... } object, or the file becomes invalid JSON:

json

{
  "mcpServers": {
    "icloud": {
      "command": "icloud-mcp",
      "env": {
        "ICLOUD_USERNAME": "you@icloud.com",
        "ICLOUD_KEYRING_SERVICE": "icloud-mcp"
      }
    }
  }
}

If the file already contains other keys, merge mcpServers in as a sibling (remember the comma between keys):

json

{
  "someExistingSetting": "...",
  "mcpServers": { "icloud": { "...": "..." } }
}

Then fully quit Claude Desktop (⌘Q, not just closing the window) and reopen it. The server shows up as a Local MCP server and its tools become available.

Notes:

First call prompts for Keychain access. macOS asks whether icloud-mcp may read the keyring item; click Always Allow to avoid repeat prompts.
Claude Desktop may rewrite this file when it saves its own preferences, dropping hand-added keys it doesn't recognize. If the server disappears after you change other settings, just re-add the mcpServers block.

Tools & resources

Tools (model-invoked):

Tool	Description
`list_mail`	List a folder (default INBOX), newest first, with optional `since_date`
`search_mail`	Full-text search the inbox (or a named folder)
`list_folders`	List the available IMAP mailbox folder names
`get_message`	Fetch one message by UID, with full body
`list_events`	Calendar events in a date window
`search_events`	Events whose title matches text, in a window
`list_calendars`	Names of all calendars
`list_contacts`	List address-book contacts (name, emails, phones, org)
`search_contacts`	Find contacts matching text across name, org, and emails
`send_mail` ⚠️	Send a plain-text email
`reply_mail` ⚠️	Reply to a message by UID (quotes original; `reply_all` optional)
`forward_mail` ⚠️	Forward a message by UID to a new recipient
`create_event` ⚠️	Create a calendar event
`update_event` ⚠️	Edit an event by UID (only the fields you pass)
`delete_event` ⚠️	Delete an event by UID
`create_contact` ⚠️	Create a new contact
`update_contact` ⚠️	Edit a contact by UID (merges into the existing vCard)
`delete_contact` ⚠️	Delete a contact by UID

⚠️ Write tools require ICLOUD_ENABLE_WRITES=1 and confirm each action — see Writes (opt-in).

Resources (passive context):

URI	Description
`icloud://mail/inbox/recent`	Most recent inbox messages
`icloud://calendar/today`	Today + tomorrow's events

Behavior notes

Empty/missing headers: messages whose Subject header is absent or present-but-blank render as (no subject); a blank/absent From renders as (unknown). (Some mail has an empty subject line rather than no subject line at all — both are normalized.)
Snippets prefer the text/plain part; for HTML-only mail, tags are stripped (<style>/<script>/<head> content discarded) so you still get a readable preview.
Double-wrapped bodies: some senders (e.g. USPS Informed Delivery) embed a redundant MIME header block at the top of the decoded body. A leading Content-*/MIME-Version header block is stripped so those headers don't leak into the snippet or body.
since_date is date-granular and evaluated in the IMAP server's timezone (UTC for iCloud), so a since_date of today can include late-yesterday messages in your local time.

Development

bash

.venv/bin/pytest            # run the fixture-based test suite (no live account)
.venv/bin/mcp dev -m icloud_mcp.server   # interactive MCP Inspector

Security notes

The app-specific password lives in the OS keyring only — never in .env, never committed.
Read access (mail, calendar, contacts) cannot mutate anything; the IMAP session is opened read-only.
Writes are off by default. They require ICLOUD_ENABLE_WRITES=1 and an interactive confirmation per action, and mail is sent over a separate SMTP connection isolated from the read path.
An app-specific password can be revoked at any time from appleid.apple.com without affecting your Apple ID.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or sponsored by Apple Inc. iCloud is a trademark of Apple Inc.

Install

Configuration

Environment variables

ICLOUD_USERNAMErequired

Your Apple ID email (the IMAP/CalDAV username).

ICLOUD_KEYRING_SERVICE

OS-keyring service name to read the app-specific password from. Default: icloud-mcp. Set to reuse an existing entry.

ICLOUD_APP_PASSWORDsecret

App-specific password. Fallback only; preferred storage is the OS keyring. Used only when no keyring entry is found.

ICLOUD_ENABLE_WRITES

Enable mutating tools (send/reply/forward mail, create/update/delete event & contact). Off by default; each write still requires interactive confirmation. Accepts 1/true/yes/on.

ICLOUD_IMAP_HOST

IMAP host override. Default: imap.mail.me.com

ICLOUD_IMAP_PORT

IMAP port override. Default: 993

ICLOUD_SMTP_HOST

SMTP host override (used only by write/send tools). Default: smtp.mail.me.com

ICLOUD_SMTP_PORT

SMTP port override. Default: 587

ICLOUD_CALDAV_URL

CalDAV base URL override. Default: https://caldav.icloud.com/

ICLOUD_CARDDAV_URL

CardDAV base URL override. Default: https://contacts.icloud.com/

ICLOUD_TZ

IANA timezone for rendering/scoping events. Default: system local time.

claude_desktop_config.json

{
  "mcpServers": {
    "icloud-mcp": {
      "command": "uvx",
      "args": [
        "icloud-mcp"
      ],
      "env": {
        "ICLOUD_USERNAME": "<YOUR_ICLOUD_USERNAME>",
        "ICLOUD_KEYRING_SERVICE": "<YOUR_ICLOUD_KEYRING_SERVICE>",
        "ICLOUD_APP_PASSWORD": "<YOUR_ICLOUD_APP_PASSWORD>",
        "ICLOUD_ENABLE_WRITES": "<YOUR_ICLOUD_ENABLE_WRITES>",
        "ICLOUD_IMAP_HOST": "<YOUR_ICLOUD_IMAP_HOST>",
        "ICLOUD_IMAP_PORT": "<YOUR_ICLOUD_IMAP_PORT>",
        "ICLOUD_SMTP_HOST": "<YOUR_ICLOUD_SMTP_HOST>",
        "ICLOUD_SMTP_PORT": "<YOUR_ICLOUD_SMTP_PORT>",
        "ICLOUD_CALDAV_URL": "<YOUR_ICLOUD_CALDAV_URL>",
        "ICLOUD_CARDDAV_URL": "<YOUR_ICLOUD_CARDDAV_URL>",
        "ICLOUD_TZ": "<YOUR_ICLOUD_TZ>"
      }
    }
  }
}