icloud-mcp 2.0.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,12 +1,14 @@
 # icloud-mcp
 
-A Model Context Protocol (MCP) server that connects Claude Desktop to your iCloud Mail account. Manage, search, organize, and analyze 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 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
@@ -22,7 +24,7 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your iClou
 
 ## 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
 
@@ -80,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:
 
@@ -105,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:
@@ -118,11 +154,14 @@ 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
 
-Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
+You're all set. Try asking Claude:
 
-## Available Tools (46)
+- *"Show me the top senders in my iCloud inbox"*
+- *"How many unread emails do I have?"*
+
+## Available Tools (55)
 
 ### Read & Search
 
@@ -146,6 +185,15 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `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 |
@@ -189,6 +237,16 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 | `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 |
@@ -199,7 +257,7 @@ Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manag
 
 ## 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 |
 |--------|------|-------------|
@@ -238,7 +296,9 @@ Once configured, you can ask Claude things like:
 - *"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"*
-- *"How many emails would be moved if I archived everything older than 6 months?"*
+- *"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