iCloud Mail MCP server

iCloud Mail MCP

<!-- mcp-name: io.github.JulienRabault/icloud-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

BODY.PEEK — nothing is marked as read, moved or deleted behind your back.

• Read-only by default. Search and read tools use SELECT ... readonly and

rules; searchallfolders finds them where an inbox-only search can't.

• Searches every folder, not just the inbox. Replies get filed away by mail

review. send_email exists, but it is separate and explicit.

• Drafts before sends. save_draft puts a message in Drafts for you to

delete_mailbox refuses any folder that still holds some.

• Nothing destroys mail. There is no tool that deletes messages, and

lying charsets, HTML-only messages, accented server-side search.

• Handles real iCloud MIME. Modified UTF-7 folder names, quoted-printable,

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 Code

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 claudedesktopconfig.json:

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

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

Codex

In ~/.codex/config.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:

Shortened. The full README is on GitHub.