iCloud Mail MCP
A Model Context Protocol (MCP) server for . Lets an LLM read, search, file and send your Apple mail over IMAP and SMTP.
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx icloud-mail-mcp==0.1.1Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
ICLOUD_EMAIL=<value> ICLOUD_APP_PASSWORD=<secret> ICLOUD_DISPLAY_NAME=<value> claude mcp add io.github.julienrabault-icloud-mcp -- uvx icloud-mail-mcp==0.1.1รันในเทอร์มินัล
{ "mcpServers": { "io.github.julienrabault-icloud-mcp": { "command": "uvx", "args": [ "icloud-mail-mcp==0.1.1" ], "env": { "ICLOUD_EMAIL": "<value>", "ICLOUD_APP_PASSWORD": "<secret>", "ICLOUD_DISPLAY_NAME": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิด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.
SELECT ... readonly and
BODY.PEEK — nothing is marked as read, moved or deleted behind your back.search_all_folders finds them where an inbox-only search can't.save_draft puts a message in Drafts for you to
review. send_email exists, but it is separate and explicit.delete_mailbox refuses any folder that still holds some.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
Check with claude mcp list.
Add the standard config to claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonOn Windows, use the absolute path to uv.exe: desktop clients don't always
inherit your shell PATH.
In ~/.codex/config.toml:
[mcp_servers.icloud-mail]
command = "uv"
args = ["run", "--directory", "/path/to/icloud-mcp", "python", "-m", "icloud_mcp"]
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.
Read — none of these modify the mailbox:
Write — explicit by design:
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.
examples/ holds standalone scripts using the same modules — point cron or Task
Scheduler at them:
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.
skills/mailbox-search/ is a Claude Code skill that forces a sweep of every
folder before concluding a message doesn't exist:
cp -r skills/mailbox-search ~/.claude/skills/
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.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.utf7.py.text/plain part..env (gitignored) or the environment, never in code.
Settings.__repr__ omits the password.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.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.
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
Issues and pull requests welcome. Tests must pass offline — no test may require a real mailbox.
MIT
Read, search, draft, send and file iCloud Mail over IMAP and SMTP. No tool destroys mail.
{ "mcpServers": { "io.github.julienrabault-icloud-mcp": { "command": "uvx", "args": [ "icloud-mail-mcp==0.1.1" ], "env": { "ICLOUD_EMAIL": "<value>", "ICLOUD_APP_PASSWORD": "<secret>", "ICLOUD_DISPLAY_NAME": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: ICLOUD_EMAIL, ICLOUD_APP_PASSWORD, ICLOUD_DISPLAY_NAME
ICloud Mail ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Read, search, draft, send and file iCloud Mail over IMAP and SMTP. No tool destroys mail.