icloud-mcp 2.5.0 → 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Zaidi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,341 +1,235 @@
-# 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](https://claude.ai/download) 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](https://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
-
-```bash
-npm install -g icloud-mcp
-```
-
-Then find the install location:
-
-```bash
-npm root -g
-```
-
-The path varies by setup:
-
-| Setup | Typical path |
-|-------|-------------|
-| Mac with Homebrew Node | `/opt/homebrew/lib/node_modules` |
-| Mac with system Node | `/usr/local/lib/node_modules` |
-| nvm | `~/.nvm/versions/node/v20.x.x/lib/node_modules` |
-
-### 3. Verify your setup
-
-Before configuring Claude Desktop, run the doctor command to confirm everything is working:
-
-```bash
-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:
-
-```bash
-open ~/Library/Application\ Support/Claude/claude_desktop_config.json
-```
-
-Add the following under `mcpServers`, replacing the path with your npm root from step 2:
-
-```json
-{
-  "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):
-
-```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:
-
-```
-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 (65)
-
-### 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 |
-| `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 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 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 |
-| `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) |
-
-### 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 |
-
-### Contacts (CardDAV)
-
-| Tool | Description |
-|------|-------------|
-| `list_contacts` | List contacts from iCloud Contacts; supports `limit`, `offset` for pagination |
-| `search_contacts` | Search contacts by name, email, or phone number |
-| `get_contact` | Get full details for a specific contact by ID |
-| `create_contact` | Create a new contact; supports name, phones, emails, address, org, birthday, note |
-| `update_contact` | Update an existing contact; only provided fields are changed |
-| `delete_contact` | Permanently delete a contact |
-
-### Calendar (CalDAV)
-
-| Tool | Description |
-|------|-------------|
-| `list_calendars` | List all iCloud calendars with name, ID, and supported event types |
-| `list_events` | List events in a calendar within a date range; supports `since`, `before`, `limit` |
-| `get_event` | Get full details of a specific event by ID |
-| `create_event` | Create a new event; supports title, start/end, timezone, all-day, description, location, recurrence |
-| `update_event` | Update an existing event; only provided fields are changed |
-| `delete_event` | Permanently delete a calendar event |
-| `search_events` | Search for events by title across all calendars; supports date range |
-
-### Session Log
-
-| Tool | Description |
-|------|-------------|
-| `log_write` | Write a step to the session log |
-| `log_read` | Read the session log |
-| `log_clear` | Clear the session log and start fresh |
-
-## Filters
-
-`bulk_move`, `bulk_delete`, `bulk_flag`, `search_emails`, `count_emails`, and rules all accept any combination of these filters:
-
-| Filter | Type | Description |
-|--------|------|-------------|
-| `sender` | string | Match exact sender email address |
-| `domain` | string | Match any sender from this domain (e.g. `substack.com`) |
-| `subject` | string | Keyword to match in subject |
-| `before` | string | Only emails before this date (YYYY-MM-DD) |
-| `since` | string | Only emails since this date (YYYY-MM-DD) |
-| `unread` | boolean | `true` for unread only, `false` for read only |
-| `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 (requires narrow pre-filters — scans up to 500 candidates) |
-
-## 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"*
-- *"Find John Smith's phone number in my contacts"*
-- *"Add a new contact: Jane Doe, jane@example.com, +1 555 123 4567"*
-- *"What's on my calendar next week?"*
-- *"Create an event: dentist appointment Monday at 10am Eastern"*
-- *"Find all my calendar events about 'team meeting'"*
-
-## 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](https://appleid.apple.com)
-
-## License
-
-MIT
+# icloud-mcp
+
+Maintained Model Context Protocol (MCP) server for iCloud Mail, Contacts, Calendar, and Reminders. Version **2.7.0** (86 tools).
+
+## Features
+
+- Read, search, and paginate any mailbox, including threads, attachments, and unsubscribe links
+- Send, reply, forward, and save drafts over SMTP
+- Bulk move, delete, flag, and mark-read, with a safe copy-verify-delete pipeline for moves
+- Saved rules, digest state, and a session log for long cleanups
+- Contacts over CardDAV, calendars over CalDAV (including bulk create/update/delete and conflict checks), and Reminders
+- `dryRun` on every delete, every move that removes the original, and every bulk operation. A dry run reports a `changes` list of exactly what would be affected and does not modify anything
+
+## Prerequisites
+
+- Node.js 20 or newer
+- Claude Desktop or Claude Code
+- An iCloud account with an app-specific password
+
+## Install
+
+Install from npm:
+
+```bash
+npm install -g icloud-mcp
+```
+
+Or skip the install and let `npx` fetch it on demand (the configs below use this).
+
+Confirm the server can reach iCloud:
+
+```bash
+IMAP_USER="you@icloud.com" IMAP_PASSWORD="your-app-specific-password" npx -y icloud-mcp --doctor
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "icloud-mail": {
+      "command": "npx",
+      "args": ["-y", "icloud-mcp"],
+      "env": {
+        "IMAP_USER": "you@icloud.com",
+        "IMAP_PASSWORD": "your-app-specific-password"
+      }
+    }
+  }
+}
+```
+
+If Claude Desktop cannot find `npx`, use its full path (`which npx`). With a global install, `"command": "icloud-mcp"` and no `args` also works. Quit Claude Desktop completely and reopen it.
+
+### Claude Code
+
+```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
+```
+
+### From source
+
+```bash
+git clone https://github.com/adamzaidi/icloud-mcp.git
+cd icloud-mcp
+npm install
+```
+
+Point the configs above at `node /absolute/path/to/icloud-mcp/index.js` instead of `npx -y icloud-mcp`. To run from a checkout, copy `.mcp.json.example` to `.mcp.json` (that file is gitignored) and export `ICLOUD_EMAIL` and `ICLOUD_APP_PASSWORD` in your shell.
+
+Additional IMAP accounts use `IMAP_ACCOUNT_N_USER`, `IMAP_ACCOUNT_N_PASSWORD`, `IMAP_ACCOUNT_N_HOST`, `IMAP_ACCOUNT_N_SMTP_HOST`, and `IMAP_ACCOUNT_N_NAME`.
+
+## Local data
+
+Rules, the move manifest, digest state, and the session log are written outside the repository, in your home directory:
+
+- `~/.icloud-mcp-rules.json`
+- `~/.icloud-mcp-move-manifest.json`
+- `~/.icloud-mcp-digest.json`
+- `~/.icloud-mcp-session.json`
+
+Set `ICLOUD_MCP_DATA_DIR` to store those files somewhere else. Do not point it at the git checkout. Contact exports, CRM notes, `.env`, and digest output belong outside the repo; `.gitignore` already excludes the usual local folders.
+
+## Available tools (86)
+
+`dryRun: true` returns `{ dryRun: true, changes: [...] }` plus the existing count fields (`wouldDelete`, `wouldMove`, and so on). Omitted or false performs the change.
+
+### Mail
+
+| Tool | Description | dryRun |
+|------|-------------|--------|
+| `list_accounts` | List all configured email accounts (names and IMAP hosts). Use the account name in any mail tool's account parameter. |  |
+| `get_inbox_summary` | Get a summary of a mailbox including total, unread, and recent email counts |  |
+| `get_mailbox_summary` | Get total, unread, and recent email counts for any specific mailbox/folder |  |
+| `get_top_senders` | Get the top senders by email count from a sample of the inbox |  |
+| `get_unread_senders` | Get top senders of unread emails |  |
+| `get_emails_by_sender` | Get all emails from a specific sender |  |
+| `read_inbox` | Read emails from an inbox with pagination. Supports multiple accounts. |  |
+| `get_email` | Get full content of a specific email by UID |  |
+| `search_emails` | Search emails by keyword or targeted field queries, with optional filters for date, read status, domain, and more |  |
+| `count_emails` | Count how many emails match a set of filters without moving or deleting them. Use this before bulk_move or bulk_delete to preview how many emails will be affected. |  |
+| `bulk_move` | Move emails matching any combination of filters from one mailbox to another. Uses safe copy-verify-delete with fingerprint verification and a persistent manifest. Use dryRun: true to preview without making changes. | yes |
+| `bulk_delete` | Delete emails matching any combination of filters. Processes in chunks of 500 with per-chunk timeouts for reliability. Use dryRun: true to preview without making changes. | yes |
+| `bulk_flag` | Flag or unflag emails matching any combination of filters in bulk | yes |
+| `bulk_delete_by_sender` | Delete all emails from a specific sender | yes |
+| `bulk_move_by_sender` | Move all emails from a specific sender to a folder | yes |
+| `bulk_delete_by_subject` | Delete all emails matching a subject pattern | yes |
+| `bulk_mark_read` | Mark all emails as read, optionally filtered by sender | yes |
+| `bulk_mark_unread` | Mark all emails as unread, optionally filtered by sender | yes |
+| `delete_older_than` | Delete all emails older than a certain number of days | yes |
+| `get_emails_by_date_range` | Get emails between two dates |  |
+| `flag_email` | Flag or unflag a single email |  |
+| `mark_as_read` | Mark a single email as read or unread |  |
+| `delete_email` | Delete a single email | yes |
+| `move_email` | Move a single email to a different mailbox/folder | yes |
+| `list_mailboxes` | List all mailboxes/folders in iCloud Mail |  |
+| `create_mailbox` | Create a new mailbox/folder |  |
+| `rename_mailbox` | Rename an existing mailbox/folder |  |
+| `delete_mailbox` | Delete a mailbox/folder. The folder must be empty first. | yes |
+| `empty_trash` | Permanently delete all emails in the trash (Deleted Messages or Trash folder). Use dryRun: true to preview first. | yes |
+| `get_move_status` | Check the status of the current or most recent bulk move operation. Shows progress, chunk statuses, and any failures. Call this to monitor a long-running move or inspect a failed one. |  |
+| `abandon_move` | Abandon an in-progress move operation so a new one can start. Only use if you are certain the operation should not be resumed. Emails already moved will not be returned to source. |  |
+| `log_write` | Write a step to the session log. Use this to record your plan before starting, and after each completed step. Helps maintain progress across long operations. |  |
+| `log_read` | Read the current session log to see what has been done so far. |  |
+| `log_clear` | Clear the session log and start fresh. Use this at the start of a new task. |  |
+| `list_attachments` | List all attachments in an email without downloading them. Returns filename, MIME type, size, and IMAP part ID for each attachment. |  |
+| `get_attachment` | Download a specific attachment from an email. Returns the file content as base64-encoded data. Use list_attachments first to get the partId. Maximum 20 MB per request; use offset+length for larger files. |  |
+| `get_unsubscribe_info` | Get the List-Unsubscribe header from an email, parsed into email and URL components. Useful for AI-assisted inbox cleanup. |  |
+| `mark_older_than_read` | Mark all unread emails older than N days as read. Useful for bulk triage of a cluttered inbox. | yes |
+| `bulk_move_by_domain` | Move all emails from a specific domain to a folder. Convenience wrapper around bulk_move with a domain filter. | yes |
+| `get_email_raw` | Get the raw RFC 2822 source of an email (full headers + MIME body) as base64-encoded data. Useful for debugging or export. Capped at 1 MB. |  |
+| `bulk_flag_by_sender` | Flag or unflag all emails from a specific sender | yes |
+| `archive_older_than` | Safely move emails older than N days from a source mailbox to an archive folder. Uses the same safe copy-verify-delete pipeline as bulk_move. Use dryRun: true to preview. | yes |
+| `get_storage_report` | Estimate storage usage by size bucket and identify top senders by email size. Uses SEARCH LARGER queries for bucketing and samples large emails for sender analysis. |  |
+| `get_thread` | Find all emails in the same thread as a given email. Uses subject matching + References/In-Reply-To header filtering. Note: iCloud does not support server-side threading — results are approximate. |  |
+| `create_rule` | Create a saved rule that applies a specific action to emails matching a set of filters. Rules are stored persistently and can be run on demand or all at once with run_all_rules. |  |
+| `list_rules` | List all saved rules with their filters, actions, and run history. |  |
+| `run_rule` | Run a specific saved rule by name. Use dryRun: true to preview what would be affected without making changes. | yes |
+| `delete_rule` | Delete a saved rule by name. | yes |
+| `run_all_rules` | Run all saved rules in sequence. Use dryRun: true to preview all rules without making changes. | yes |
+| `compose_email` | Compose and send a new email via iCloud SMTP. The From address is always your iCloud account. Supports plain text, HTML, or both (multipart/alternative). |  |
+| `reply_to_email` | Reply to an existing email. Automatically sets correct threading headers (In-Reply-To, References) and prefixes the subject with Re:. Supports plain text and/or HTML body. |  |
+| `forward_email` | Forward an existing email to one or more recipients. Fetches the original email body and includes it as a forwarded message block. Supports plain text and/or HTML note. |  |
+| `save_draft` | Save a draft email to your iCloud Drafts folder without sending it. Supports plain text, HTML, or both. The draft can be edited and sent later from Mail.app or iCloud.com. |  |
+| `get_digest_state` | Get the current inbox digest state — last run timestamp, processed email UIDs (to skip on next run), pending actions, and per-sender skip counts for smart unsubscribe. |  |
+| `update_digest_state` | Update the digest state after a run. Merges new processed UIDs into the existing list, updates lastRun, replaces pendingActions, and accumulates per-sender skip counts. |  |
+
+### Contacts
+
+| Tool | Description | dryRun |
+|------|-------------|--------|
+| `list_contacts` | List contacts from iCloud Contacts. Returns names, phones, emails, and other fields. |  |
+| `search_contacts` | Search iCloud Contacts by name, email address, or phone number. |  |
+| `get_contact` | Get full details for a specific contact by ID. Use list_contacts or search_contacts to find a contactId. |  |
+| `create_contact` | Create a new contact in iCloud Contacts. |  |
+| `update_contact` | Update an existing contact in iCloud Contacts. Only provided fields are changed; others are preserved. |  |
+| `delete_contact` | Delete a contact from iCloud Contacts permanently. | yes |
+
+### Calendar
+
+| Tool | Description | dryRun |
+|------|-------------|--------|
+| `list_calendars` | List all calendars in iCloud Calendar (e.g. Personal, Work, School). Returns calendarId, name, and supported event types. |  |
+| `create_calendar` | Create a new event calendar in iCloud Calendar. Fails if a calendar with that name already exists. |  |
+| `delete_calendar` | Delete an iCloud event calendar by exact name or calendarId. The calendar must have no events (past or future); delete them first with bulk_delete_events. Will not delete Reminders lists. | yes |
+| `list_events` | List events in a specific iCloud calendar within a date range. Use list_calendars first to get a calendarId. |  |
+| `get_event` | Get full details of a specific calendar event by its ID. |  |
+| `create_event` | Create a new event in an iCloud calendar. For all-day events use allDay:true and YYYY-MM-DD for start/end. |  |
+| `update_event` | Update an existing calendar event. Only provided fields are changed; others are preserved. |  |
+| `delete_event` | Delete a calendar event permanently from iCloud Calendar. | yes |
+| `search_events` | Search for events by title/summary across all calendars within an optional date range. |  |
+| `bulk_update_events` | Update multiple calendar events in one call. Each update object must include eventId and only the fields to change. | yes |
+| `list_events_multi` | List events from multiple calendars in one call. Returns events grouped by calendar ID. |  |
+| `bulk_create_events` | Create multiple calendar events in one call. Much more efficient than calling create_event repeatedly. Each event in the array uses the same fields as create_event. | yes |
+| `bulk_delete_events` | Delete multiple calendar events in one call. Much more efficient than calling delete_event repeatedly. | yes |
+| `detect_conflicts` | Detect scheduling conflicts and tight gaps between events across multiple calendars. Compares all non-all-day events on the same date from different calendars. |  |
+
+### Reminders
+
+| Tool | Description | dryRun |
+|------|-------------|--------|
+| `list_reminder_lists` | List all Reminders lists in iCloud Reminders (e.g. "Reminders", "Work", "Shopping"). Returns name, id, and count per list. |  |
+| `create_reminder_list` | Create a new Reminders list in iCloud Reminders. Fails if a list with that name already exists. |  |
+| `rename_reminder_list` | Rename a Reminders list. The old name must match exactly one list, and the new name must not already be in use. | yes |
+| `delete_reminder_list` | Delete a Reminders list. The list must be empty first, and the name must match exactly one list. | yes |
+| `list_reminders` | List reminders from iCloud Reminders. Omit listName to fetch from all lists. |  |
+| `get_reminder` | Get full details of a specific reminder by ID. |  |
+| `create_reminder` | Create a new reminder in iCloud Reminders. |  |
+| `update_reminder` | Update an existing reminder. Only provided fields are changed; others are preserved. |  |
+| `complete_reminder` | Mark a reminder as completed in iCloud Reminders. |  |
+| `delete_reminder` | Delete a reminder from iCloud Reminders permanently. | yes |
+
+Listing reminders reads each property for the whole list in one batch. A list of zero or one reminder is coerced to an array before it is indexed. If Reminders.app stalls, the tool says the script timed out after 90 seconds instead of reporting an iCloud network timeout. A timed-out create, update, or delete may still have been applied.
+
+### Email to calendar
+
+| Tool | Description | dryRun |
+|------|-------------|--------|
+| `suggest_event_from_email` | Fetch an email and return its content formatted for calendar event extraction. After calling this tool, extract the event fields from the returned content (pay attention to _dateAnchor for resolving relative dates like "Tuesday"), present a summary to the user for confirmation, then call create_event. No API key required. |  |
+
+## Filters
+
+`bulk_move`, `bulk_delete`, `bulk_flag`, `search_emails`, `count_emails`, and rules accept any combination of: `sender`, `domain`, `subject`, `before`, `since`, `unread`, `flagged`, `larger`, `smaller`, `hasAttachment`, and `account`.
+
+A `domain` filter searches both the bare domain and `@domain`. iCloud's FROM search misses some senders when given only the bare domain. Subdomains are not matched: a filter of `example.com` does not find mail from `someone@mail.example.com`. When a keyword and a domain are both set, `search_emails` keeps both conditions.
+
+## Safe move
+
+`bulk_move`, `bulk_move_by_sender`, `bulk_move_by_domain`, and `archive_older_than` copy, verify fingerprints in the destination, then remove the source. `get_move_status` and `abandon_move` inspect or clear the manifest.
+
+## Connections
+
+An idle iCloud IMAP connection times out after 60 seconds of silence. The server logs the error and that tool call fails. The process stays up. Saving a draft uses its own IMAP connection and attaches the same handler.
+
+## Tests
+
+`npm test` runs the offline suite only. It mocks IMAP, CardDAV, CalDAV, and Reminders, and it does not contact iCloud or send mail.
+
+`npm run test:live` runs the dummy-data suite in `tests/live-destructive.test.js`. It stays skipped unless `ICLOUD_MCP_LIVE=1`, `IMAP_USER`, and `IMAP_PASSWORD` are all set. It creates dummy contacts, reminders, calendar events, and messages appended into a temp folder, then deletes those dummies. It does not send mail. Set `LIVE_CALENDAR` to the calendar that should receive the dummy events. Calendar tests are skipped when that variable is unset. Delete tools run as a dry run first and skip the real delete unless that preview names exactly the dummies from this run.
+
+`npm run test:send` runs `tests/test.js`. It stays skipped unless `ICLOUD_MCP_SEND=1`, `IMAP_USER`, and `IMAP_PASSWORD` are all set. Every message it sends goes only to the account in `IMAP_USER`. Reply, reply-all, and forward act on a seed that account just sent to itself, never on other inbox mail. Before each send, a guard checks every To, Cc, and Bcc recipient (case and surrounding whitespace ignored) and aborts the run if any address is anyone else.
+
+`dryRun: true` on a delete, a move that removes the original, or a bulk change returns `{ dryRun: true, changes: [...] }` and does not write. Omit it, or pass false, to perform the change.
+
+## Security
+
+Credentials stay in your local MCP client config. The server runs on your machine. Revoke an app-specific password at [appleid.apple.com](https://appleid.apple.com).
+
+## License
+
+MIT