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
- **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:
From source:
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:
Claude Code
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:
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 |