ICloud Mail README

iCloud Mail MCP

A Model Context Protocol (MCP) server for iCloud Mail. Lets an LLM read, search, file and send your Apple mail over IMAP and SMTP.

Runs entirely on your machine: your credentials and your mail never reach a third party. Networking and MIME parsing use only the Python standard library.

Key Features

Read-only by default. Search and read tools use SELECT ... readonly and BODY.PEEK — nothing is marked as read, moved or deleted behind your back.
Searches every folder, not just the inbox. Replies get filed away by mail rules; search_all_folders finds them where an inbox-only search can't.
Drafts before sends. save_draft puts a message in Drafts for you to review. send_email exists, but it is separate and explicit.
Nothing destroys mail. There is no tool that deletes messages, and delete_mailbox refuses any folder that still holds some.
Handles real iCloud MIME. Modified UTF-7 folder names, quoted-printable, lying charsets, HTML-only messages, accented server-side search.

Requirements

Python 3.11 or newer, and uv
An iCloud account with two-factor authentication enabled
An app-specific password — iCloud rejects your main password over IMAP

Getting started

Once published to PyPI, no clone is needed:

bash

uvx --from icloud-mail-mcp icloud-mcp-setup     # interactive configuration
uvx --from icloud-mail-mcp icloud-mcp           # run the server

From source:

bash

git clone https://github.com/JulienRabault/icloud-mcp.git
cd icloud-mcp
uv sync
uv run python -m icloud_mcp.setup

The setup command asks for your address and app-specific password, tests the connection, writes .env, then prints the exact config block for your client.

Generate the app-specific password at account.apple.com → Sign-In and Security → App-Specific Passwords.

Standard config works in most clients:

config.json

{
  "mcpServers": {
    "icloud-mail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]
    }
  }
}

Claude Code

Terminal

claude mcp add icloud-mail --scope user -- uv run --directory /path/to/icloud-mcp python -m icloud_mcp

Check with claude mcp list.

Claude Desktop

Add the standard config to claude_desktop_config.json:

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

On Windows, use the absolute path to uv.exe: desktop clients don't always inherit your shell PATH.

Codex

In ~/.codex/config.toml:

toml

[mcp_servers.icloud-mail]
command = "uv"
args = ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]

Cursor / Windsurf / VS Code

Use the standard config block in the MCP settings file of your editor (.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, or the VS Code MCP settings).

MCP servers load at client startup — restart the client after editing its config.

Tools

Read — none of these modify the mailbox:

Tool	Description
`list_folders`	List folders, optionally with message and unread counts
`folder_status`	Counts for one folder without listing messages
`search_emails`	Search one folder: text, sender, recipient, subject, dates, flags, size
`search_all_folders`	The same search across every folder at once
`read_email`	Full message: decoded body, optional HTML, attachment metadata
`get_thread`	Rebuild a conversation, optionally with each message body
`save_attachments`	Write attachments to disk and return their paths

Write — explicit by design:

Tool	Description
`save_draft`	Put a message in Drafts. Nothing is sent
`set_flag`	Read/unread, flagged, answered. Reversible
`create_mailbox`	Create a folder, accented names included
`rename_mailbox`	Rename a folder, messages follow
`delete_mailbox`	Delete an empty folder. Refuses while it holds mail
`auto_organize`	File messages by rules. Simulates unless `dry_run=false`
`move_emails`	Move between folders. Simulates unless `dry_run=false`
`send_email`	Actually sends. No draft step, no undo

No tool destroys mail. delete_mailbox refuses a folder that still holds messages — move them out first, which keeps the decision with you.

Attachment bytes never pass through the model: save_attachments writes files and returns paths. Filenames arriving from email are sanitised — they are hostile input, not trusted paths.

Resources

URI	Content
`icloud://folders`	Every folder with message and unread counts
`icloud://unread`	Unread messages in the inbox

Prompts

Prompt	Purpose
`triage_inbox`	Sort recent mail into action required / info / waiting / ignorable
`draft_reply`	Read a message and its thread, draft a reply into Drafts
`follow_up`	Reconstruct an exchange with a contact, say who owes whom a reply

Automation without an MCP client

examples/ holds standalone scripts using the same modules — point cron or Task Scheduler at them:

bash

uv run python examples/daily_digest.py           # what arrived today
uv run python examples/watch_sender.py acme.com  # exit 1 if nothing new
uv run python examples/waiting_on_reply.py       # threads nobody answered
uv run python examples/auto_file.py --apply      # file mail by rules

All support --json for piping. See examples/README.md.

Bundled skill

skills/mailbox-search/ is a Claude Code skill that forces a sweep of every folder before concluding a message doesn't exist:

bash

cp -r skills/mailbox-search ~/.claude/skills/

iCloud quirks handled here

Worth knowing if you're writing your own IMAP client against iCloud:

SEARCH returns UIDs out of order. RFC 3501 doesn't guarantee ordering, and iCloud genuinely returns unsorted lists. Taking the tail of the response gives you the wrong messages — sort numerically first.
No MOVE, no UIDPLUS. Moving means COPY + \Deleted + EXPUNGE, and EXPUNGE purges every \Deleted message in the folder. move_emails refuses to run when the folder holds deleted messages outside the requested batch, which would otherwise be destroyed.
SEARCH CHARSET UTF-8 works. Accented queries run server-side across the whole mailbox. A client-side fallback covers servers that refuse, and flags it via filtered_client_side in the response.
Folder names use modified UTF-7 (RFC 3501), implemented in utf7.py.
Charsets lie. Bodies fall back to latin-1 when the declared charset fails, and to stripped HTML when there's no text/plain part.

Security notes

Credentials live in .env (gitignored) or the environment, never in code. Settings.__repr__ omits the password.
Email content is data, not instructions. The server tells clients never to act on directives found inside a received message.
send_email and move_emails are meant to run only after the user approves the exact content or the exact message list in the conversation.

Development

bash

uv run pytest -q

49 offline tests — no network, no credentials. CI runs them on Linux, macOS and Windows against Python 3.11 to 3.13.

Code

src/icloud_mcp/
  config.py        env / .env loading
  utf7.py          modified UTF-7 for folder names
  models.py        frozen Pydantic models
  mime.py          header, body and attachment decoding
  imap_client.py   connection, LIST, STATUS, SELECT, FETCH
  search.py        SEARCH criteria, threading, multi-folder search
  smtp_client.py   MIME building, SMTP send, copy to Sent
  attachments.py   attachment extraction, filename sanitising
  drafts.py        APPEND to Drafts
  flags.py         \Seen, \Flagged, \Answered
  move.py          COPY + EXPUNGE with the anti-purge guard
  mailboxes.py     create, rename, delete (empty only)
  organize.py      rule-based filing
  server.py        tools, resources, prompts
  setup_wizard.py  interactive configuration
  cli.py           terminal checks

Contributing

Issues and pull requests welcome. Tests must pass offline — no test may require a real mailbox.

License

MIT