iCloud MCP Server

icloud-mcp

A Model Context Protocol (MCP) server that connects Claude to your iCloud account — Mail, Contacts, and Calendar. Read, search, organize, send, and automate across the full iCloud suite.

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
• 👤 Contacts — list, search, create, update, and delete iCloud Contacts via CardDAV
• 📅 Calendar — list calendars, query events by date, create/update/delete events via CalDAV

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