io.github.JulienRabault/icloud-mcp

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:

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

From source:

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:

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

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

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

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

Tools

Read — none of these modify the mailbox:

... View full README on GitHub