icloud-mcp

A Model Context Protocol (MCP) server that connects Claude to your iCloud Mail account. Read, search, organize, send, and automate your inbox directly through Claude.

Features

• 📬 Read and paginate through any mailbox

• 🔍 Search emails by keyword, sender, subject, body, date range, and more

• 🧵 Find email threads by References/In-Reply-To chain

• ✉️ Send emails, reply, forward, and save drafts via iCloud SMTP

• 📋 Create saved rules to auto-route emails on demand

• 🗑️ Bulk delete emails by any combination of filters

• 📁 Bulk move emails between folders with safe copy-verify-delete

• 📦 Archive emails older than N days to any folder

• 📊 Analyze top senders and storage usage to identify inbox clutter

• 🔢 Count emails matching any filter before taking action

• ✅ Mark emails as read/unread, flag/unflag in bulk or individually

• 📎 List and download email attachments (supports paginated byte-range fetching for large files)

• 🔗 Extract List-Unsubscribe links for AI-assisted cleanup

• 🗂️ List, create, rename, and delete mailboxes

• 🔄 Dry run mode for bulk operations — preview before committing

• 🔐 Safe move — emails are fingerprinted and verified in the destination before removal from source

• 📝 Session logging — Claude tracks progress across long multi-step operations

Prerequisites

• Claude Desktop or Claude Code

• Node.js v20 or higher

• An iCloud account with an app-specific password

Setup

1. Generate an Apple App-Specific Password

1. Go to appleid.apple.com

2. Sign in and navigate to Sign-In and Security → App-Specific Passwords

3. Click + to generate a new password

4. Label it something like Claude MCP and save the generated password

2. Install the package

npm install -g icloud-mcp

Then find the install location:

npm root -g

The path varies by setup:

3. Verify your setup

Before configuring Claude Desktop, run the doctor command to confirm everything is working:

IMAP_USER="you@icloud.com" IMAP_PASSWORD="your-app-specific-password" node $(npm root -g)/icloud-mcp/index.js --doctor

You should see:

icloud-mcp doctor
─────────────────────────────
✅ IMAP_USER is set
✅ IMAP_PASSWORD is set
✅ IMAP_USER looks like an email address
✅ Connected to imap.mail.me.com:993
✅ Authenticated as you@icloud.com
✅ INBOX opened (12453 messages)
─────────────────────────────
All checks passed. Ready to use with Claude Desktop.

If any step fails, a plain-English explanation and suggested fix will be shown.

4. Connect to Claude

Claude Desktop

Open your Claude Desktop config file:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the following under mcpServers, replacing the path with your npm root from step 2:

{
  "mcpServers": {
    "icloud-mail": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/icloud-mcp/index.js"],
      "env": {
        "IMAP_USER": "you@icloud.com",
        "IMAP_PASSWORD": "your-app-specific-password"
      }
    }
  }
}

Then fully quit Claude Desktop (Cmd+Q) and reopen it.

Claude Code

Run this command once to register the server for your user account (available across all projects):

claude mcp add icloud-mail \
  --scope user \
  -e IMAP_USER=you@icloud.com \
  -e IMAP_PASSWORD=your-app-specific-password \
  -- node $(npm root -g)/icloud-mcp/index.js

Or use npx to avoid needing a global install:

claude mcp add icloud-mail \
  --scope user \
  -e IMAP_USER=you@icloud.com \
  -e IMAP_PASSWORD=your-app-specific-password \
  -- npx -y icloud-mcp

Verify it registered correctly:

claude mcp list

Running from source? Copy .mcp.json.example to .mcp.json, set your credentials in your shell, then run claude from the repo directory. Claude Code will pick up the config automatically.

5. Add Custom Instructions (Recommended)

For large inbox operations, add the following to Claude Desktop's custom instructions to ensure Claude stays on track and checks in with you regularly. Go to Claude Desktop → Settings → Custom Instructions and add:

When using icloud-mail tools:
1. Before starting any multi-step operation, call log_clear then log_write with your full plan
2. After every single tool call, call log_write with what you did and the result
3. After every 3 tool calls, stop and summarize progress to the user and wait for confirmation before continuing
4. Never assume a bulk operation succeeded — always verify with count_emails after
5. If you are ever unsure what you have done so far, call log_read before proceeding

6. Start using it

You're all set. Try asking Claude:

• "Show me the top senders in my iCloud inbox"

• "How many unread emails do I have?"

Available Tools (55)

Read & Search

Send & Draft

Write

Bulk Operations

Mailbox Management

Move Tracking

Saved Rules

Session Log

Filters

bulk_move, bulk_delete, bulk_flag, search_emails, count_emails, and rules all accept any combination of these filters:

Safe Move

All bulk move operations (bulk_move, bulk_move_by_sender, bulk_move_by_domain, archive_older_than) use a three-phase copy-verify-delete approach:

1. Copy — all emails are copied to the destination in chunks

2. Verify — every email is fingerprinted and confirmed present in the destination

3. Delete — source emails are removed in a single EXPUNGE only after verification passes

A persistent manifest at ~/.icloud-mcp-move-manifest.json tracks progress so a crash or dropped connection never results in data loss. Use get_move_status to inspect any operation and abandon_move to clear a stuck one.

Example Usage

Once configured, you can ask Claude things like:

• "Show me the top senders in my iCloud inbox"

• "What's eating the most storage in my inbox?"

• "How many unread emails do I have from substack.com?"

• "Find all emails in this thread and summarize the conversation"

• "Move all emails from substack.com older than 2023 to my Newsletters folder"

• "Archive everything in my inbox older than 1 year"

• "Delete all unread emails from linkedin.com before 2022"

• "What's the unsubscribe link for this newsletter?"

• "Show me the 3 largest attachments in my inbox this month"

• "Flag all unread emails from my bank"

• "Create a rule that moves all emails from spotify.com to bulk-mail/services"

• "Reply to the last email from John and cc Sarah"

• "Draft a follow-up email to the team about the Q1 report"

Security

• Your credentials are stored only in your local Claude Desktop config file

• The server runs entirely on your machine — no data is sent to any third party

• App-specific passwords can be revoked at any time from appleid.apple.com

License

MIT