icloud-mcp 2.0.0 → 2.3.0

package/.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "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",
+      "WebSearch",
+      "WebFetch(domain:www.mdcourts.gov)",
+      "WebFetch(domain:probonomd.org)",
+      "WebFetch(domain:www.courts.state.md.us)",
+      "WebFetch(domain:msa.maryland.gov)",
+      "WebFetch(domain:www.harford.edu)",
+      "WebFetch(domain:thedailyrecord.com)",
+      "WebFetch(domain:ballotpedia.org)",
+      "mcp__icloud-mail__compose_email"
+    ]
+  },
+  "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 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
@@ -19,10 +21,12 @@ A Model Context Protocol (MCP) server that connects Claude Desktop to your iClou
 - 🔄 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)
+- [Claude Desktop](https://claude.ai/download) or Claude Code
 - Node.js v20 or higher
 - An iCloud account with an app-specific password
 
@@ -80,7 +84,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 +111,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 +156,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
+
+You're all set. Try asking Claude:
 
-Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
+- *"Show me the top senders in my iCloud inbox"*
+- *"How many unread emails do I have?"*
 
-## Available Tools (46)
+## Available Tools (65)
 
 ### Read & Search
 
@@ -146,6 +187,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 +239,39 @@ 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 |
+
+### 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 |
@@ -199,7 +282,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 +321,14 @@ 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"*
+- *"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