icloud-mcp 1.9.0 → 2.2.0

package/.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__icloud-mail__list_mailboxes",
+      "mcp__icloud-mail__get_top_senders",
+      "mcp__icloud-mail__get_unread_senders",
+      "mcp__icloud-mail__get_storage_report",
+      "mcp__icloud-mail__get_mailbox_summary",
+      "mcp__icloud-mail__create_mailbox",
+      "mcp__icloud-mail__bulk_move",
+      "mcp__icloud-mail__delete_mailbox",
+      "mcp__icloud-mail__get_inbox_summary",
+      "mcp__icloud-mail__abandon_move",
+      "mcp__icloud-mail__search_emails",
+      "mcp__icloud-mail__count_emails",
+      "mcp__icloud-mail__archive_older_than",
+      "mcp__icloud-mail__bulk_move_by_sender",
+      "mcp__icloud-mail__get_move_status",
+      "mcp__icloud-mail__bulk_move_by_domain"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "icloud-mail"
+  ]
+}

package/.mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "icloud-mail": {
+      "command": "node",
+      "args": ["./index.js"],
+      "env": {
+        "IMAP_USER": "${ICLOUD_EMAIL}",
+        "IMAP_PASSWORD": "${ICLOUD_APP_PASSWORD}"
+      }
+    }
+  }
+}

package/README.md

@@ -1,24 +1,30 @@
 # icloud-mcp
 
-A Model Context Protocol (MCP) server that connects Claude Desktop to your iCloud Mail account. Manage, search, and organize your inbox directly through Claude.
+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 your inbox
-- 🔍 Search emails by keyword, sender, date range, and more
+- 📬 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 flexible filtering
-- 📊 Analyze top senders to identify inbox clutter
+- 📁 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 being removed from the source
+- 🔐 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](https://claude.ai/download)
+- [Claude Desktop](https://claude.ai/download) or Claude Code
 - Node.js v20 or higher
 - An iCloud account with an app-specific password
 
@@ -76,7 +82,9 @@ All checks passed. Ready to use with Claude Desktop.
 
 If any step fails, a plain-English explanation and suggested fix will be shown.
 
-### 4. Configure Claude Desktop
+### 4. Connect to Claude
+
+#### Claude Desktop
 
 Open your Claude Desktop config file:
 
@@ -101,6 +109,38 @@ Add the following under `mcpServers`, replacing the path with your npm root from
 }
 ```
 
+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):
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
@@ -114,51 +154,110 @@ When using icloud-mail tools:
 5. If you are ever unsure what you have done so far, call log_read before proceeding
 ```
 
-### 6. Restart Claude Desktop
+### 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?"*
 
-Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
+## Available Tools (55)
 
-## Available Tools
+### Read & Search
 
 | Tool | Description |
 |------|-------------|
 | `get_inbox_summary` | Total, unread, and recent email counts for INBOX |
 | `get_mailbox_summary` | Total, unread, and recent email counts for any folder |
-| `get_top_senders` | Top senders by volume from a sample of recent emails (supports `sampleSize` and `maxResults`) |
-| `get_unread_senders` | Top senders of unread emails (supports `sampleSize` and `maxResults`) |
-| `read_inbox` | Paginated inbox with sender, subject, date |
-| `get_email` | Full content of a specific email by UID |
+| `list_mailboxes` | List all folders in your iCloud Mail |
+| `read_inbox` | Paginated inbox with sender, subject, date (supports unread filter) |
+| `get_email` | Full email content by UID — MIME-aware, returns body + attachments list; supports `maxChars`, `includeHeaders` |
+| `get_email_raw` | Raw RFC 2822 source as base64 (headers + MIME body, 1 MB cap) |
 | `get_emails_by_sender` | All emails from a specific address |
 | `get_emails_by_date_range` | Emails between two dates |
-| `search_emails` | Search by keyword with optional filters (date, unread, domain, etc.) |
-| `count_emails` | Count emails matching any combination of filters without modifying them |
-| `bulk_move` | Move emails matching any combination of filters between folders (supports `dryRun` and `limit`) |
-| `bulk_delete` | Delete emails matching any combination of filters (supports `dryRun`) |
-| `bulk_flag` | Flag or unflag emails matching any combination of filters |
-| `bulk_mark_read` | Mark all emails (or all from a sender) as read |
-| `bulk_mark_unread` | Mark all emails (or all from a sender) as unread |
-| `bulk_delete_by_sender` | Delete all emails from a sender |
-| `bulk_delete_by_subject` | Delete all emails matching a subject keyword |
-| `bulk_move_by_sender` | Move all emails from a sender to a folder |
+| `search_emails` | Search by keyword with filters; supports `subjectQuery`, `bodyQuery`, `fromQuery`, `queryMode` (and/or), `includeSnippet` |
+| `get_thread` | Find all emails in the same thread (subject + References/In-Reply-To matching) |
+| `count_emails` | Count emails matching any combination of filters |
+| `get_top_senders` | Top senders by volume from a sample of recent emails |
+| `get_unread_senders` | Top senders of unread emails |
+| `get_storage_report` | Estimate storage usage by size bucket and identify top large-email senders |
+| `get_unsubscribe_info` | Extract List-Unsubscribe links (email + URL) from an email |
+| `list_attachments` | List all attachments in an email (filename, MIME type, size, partId) |
+| `get_attachment` | Download an attachment as base64 (max 20 MB); supports `offset`/`length` for paginated byte-range fetching |
+
+### Send & Draft
+
+| Tool | Description |
+|------|-------------|
+| `compose_email` | Send a new email via iCloud SMTP; supports plain text, HTML, cc, bcc, replyTo |
+| `reply_to_email` | Reply to an email with correct In-Reply-To + References threading; supports `replyAll` |
+| `forward_email` | Forward an email with an optional prepended note |
+| `save_draft` | Save a draft to your Drafts folder without sending; supports plain text and HTML |
+
+### Write
+
+| Tool | Description |
+|------|-------------|
 | `flag_email` | Flag or unflag a single email |
 | `mark_as_read` | Mark a single email as read or unread |
 | `delete_email` | Move an email to Deleted Messages |
-| `move_email` | Move a single email to a folder |
+| `move_email` | Move a single email to any folder |
+
+### Bulk Operations
+
+| Tool | Description |
+|------|-------------|
+| `bulk_move` | Move emails matching any combination of filters (safe copy-verify-delete); supports `dryRun`, `limit` |
+| `bulk_move_by_sender` | Move all emails from a sender to a folder; supports `dryRun` |
+| `bulk_move_by_domain` | Move all emails from a domain to a folder; supports `dryRun` |
+| `archive_older_than` | Safely move emails older than N days to an archive folder; supports `dryRun` |
+| `bulk_delete` | Delete emails matching any combination of filters; supports `dryRun` |
+| `bulk_delete_by_sender` | Delete all emails from a sender |
+| `bulk_delete_by_subject` | Delete all emails matching a subject keyword |
 | `delete_older_than` | Delete all emails older than N days |
-| `list_mailboxes` | List all folders in your iCloud Mail |
+| `bulk_mark_read` | Mark all (or all from a sender) as read |
+| `bulk_mark_unread` | Mark all (or all from a sender) as unread |
+| `mark_older_than_read` | Mark all unread emails older than N days as read |
+| `bulk_flag` | Flag or unflag emails matching any combination of filters |
+| `bulk_flag_by_sender` | Flag or unflag all emails from a specific sender |
+| `empty_trash` | Permanently delete all emails in trash; supports `dryRun` |
+
+### Mailbox Management
+
+| Tool | Description |
+|------|-------------|
 | `create_mailbox` | Create a new folder |
 | `rename_mailbox` | Rename an existing folder |
 | `delete_mailbox` | Delete a folder (must be empty first) |
-| `empty_trash` | Permanently delete all emails in Deleted Messages |
-| `get_move_status` | Check the status of the current or most recent bulk move operation |
-| `abandon_move` | Abandon an in-progress move operation so a new one can start |
+
+### Move Tracking
+
+| Tool | Description |
+|------|-------------|
+| `get_move_status` | Check the status of the current or most recent bulk move; includes stale warning for operations >24h old |
+| `abandon_move` | Abandon an in-progress move so a new one can start |
+
+### Saved Rules
+
+| Tool | Description |
+|------|-------------|
+| `create_rule` | Create a named rule with filters + action (move/delete/mark_read/mark_unread/flag/unflag) |
+| `list_rules` | List all saved rules with last-run time and run count |
+| `run_rule` | Run a specific rule by name; supports `dryRun` |
+| `run_all_rules` | Run all saved rules in sequence; supports `dryRun` |
+| `delete_rule` | Delete a saved rule by name |
+
+### Session Log
+
+| Tool | Description |
+|------|-------------|
 | `log_write` | Write a step to the session log |
-| `log_read` | Read the session log to see what has been done so far |
+| `log_read` | Read the session log |
 | `log_clear` | Clear the session log and start fresh |
 
-## Bulk Move, Delete & Flag Filters
+## Filters
 
-`bulk_move`, `bulk_delete`, `bulk_flag`, `search_emails`, and `count_emails` all accept any combination of these filters:
+`bulk_move`, `bulk_delete`, `bulk_flag`, `search_emails`, `count_emails`, and rules all accept any combination of these filters:
 
 | Filter | Type | Description |
 |--------|------|-------------|
@@ -171,36 +270,35 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `flagged` | boolean | `true` for flagged only, `false` for unflagged only |
 | `larger` | number | Only emails larger than this size in KB |
 | `smaller` | number | Only emails smaller than this size in KB |
-| `hasAttachment` | boolean | Only emails with attachments |
-
-## Dry Run Mode
-
-Pass `dryRun: true` to `bulk_move` or `bulk_delete` to preview how many emails would be affected without making any changes:
-
-> *"How many emails would be deleted if I removed everything from linkedin.com before 2022?"*
+| `hasAttachment` | boolean | Only emails with attachments (requires narrow pre-filters — scans up to 500 candidates) |
 
 ## Safe Move
 
-All bulk move operations use a copy-verify-delete approach. Emails are fingerprinted before copying, confirmed present in the destination, and only then removed from the source. A persistent manifest at `~/.icloud-mcp-move-manifest.json` tracks progress across chunks so that a crash or connection drop mid-operation never results in data loss. Use `get_move_status` to inspect any operation and `abandon_move` to clear a stuck one.
+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:
 
-## Session Log
+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
 
-The session log persists to `~/.icloud-mcp-session.json` on your Mac — outside Claude's context window — so progress is never lost during long operations. Claude can write its plan at the start, log each completed step, and read the log back at any point to reorient itself.
+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?"*
-- *"How many emails would be moved if I archived everything from linkedin.com before 2022?"*
+- *"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"*
-- *"Move everything in my old_folders/college folder to Archive"*
-- *"How many emails do I have with attachments larger than 5MB?"*
+- *"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"*
-- *"Rename my Newsletters folder to Old Newsletters"*
-- *"Show me emails from the last week"*
+- *"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