icloud-mcp 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# 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.
+
+## Features
+
+- 📬 Read and paginate through your inbox
+- 🔍 Search emails by keyword, sender, or date range
+- 🗑️ Bulk delete emails by sender or subject
+- 📁 Move emails between folders
+- 📊 Analyze top senders to identify inbox clutter
+- ✅ Mark emails as read/unread, flag/unflag
+- 🗂️ List and create mailboxes
+
+## Prerequisites
+
+- [Claude Desktop](https://claude.ai/download)
+- 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 server
+
+```bash
+git clone https://github.com/YOUR_USERNAME/icloud-mcp.git
+cd icloud-mcp
+npm install
+```
+
+### 3. Configure Claude Desktop
+
+Open your Claude Desktop config file:
+
+```bash
+open ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+Add the following under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "icloud-mail": {
+      "command": "/opt/homebrew/bin/node",
+      "args": ["/path/to/icloud-mcp/index.js"],
+      "env": {
+        "IMAP_USER": "you@icloud.com",
+        "IMAP_PASSWORD": "your-app-specific-password"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Replace `/path/to/icloud-mcp` with the actual path where you cloned the repo, and `/opt/homebrew/bin/node` with the output of `which node`.
+
+### 4. Restart Claude Desktop
+
+Fully quit Claude Desktop (Cmd+Q) and reopen it. You should now be able to manage your iCloud inbox through Claude.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_inbox_summary` | Total, unread, and recent email counts |
+| `get_top_senders` | Top senders by volume from a sample of recent emails |
+| `get_unread_senders` | Top senders of unread emails |
+| `read_inbox` | Paginated inbox with sender, subject, date |
+| `get_email` | Full content of a specific email by UID |
+| `get_emails_by_sender` | All emails from a specific address |
+| `get_emails_by_date_range` | Emails between two dates |
+| `search_emails` | Search by keyword across subject, sender, and body |
+| `flag_email` | Flag or unflag an email |
+| `mark_as_read` | Mark an email as read or unread |
+| `delete_email` | Move an email to Deleted Messages |
+| `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 |
+| `bulk_mark_read` | Mark all emails (or all from a sender) as read |
+| `delete_older_than` | Delete all emails older than N days |
+| `move_email` | Move a single email to a folder |
+| `list_mailboxes` | List all folders in your iCloud Mail |
+| `create_mailbox` | Create a new folder |
+| `empty_trash` | Permanently delete all emails in Deleted Messages |
+
+## Example Usage
+
+Once configured, you can ask Claude things like:
+
+- *"Show me the top senders in my iCloud inbox"*
+- *"Delete all emails from no-reply@instagram.com"*
+- *"How many unread emails do I have?"*
+- *"Move all emails from newsletters@substack.com to my newsletters folder"*
+- *"Show me emails from the last week"*
+
+## Running Tests
+
+```bash
+IMAP_USER="you@icloud.com" IMAP_PASSWORD="your-app-specific-password" /opt/homebrew/bin/node test.js
+```
+
+## 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

package/index.js

@@ -0,0 +1,686 @@
+#!/usr/bin/env node
+import { ImapFlow } from 'imapflow';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const IMAP_USER = process.env.IMAP_USER;
+const IMAP_PASSWORD = process.env.IMAP_PASSWORD;
+
+if (!IMAP_USER || !IMAP_PASSWORD) {
+  process.stderr.write('Error: IMAP_USER and IMAP_PASSWORD environment variables are required\n');
+  process.exit(1);
+}
+
+function createClient() {
+  return new ImapFlow({
+    host: 'imap.mail.me.com',
+    port: 993,
+    secure: true,
+    auth: { user: IMAP_USER, pass: IMAP_PASSWORD },
+    logger: false
+  });
+}
+
+async function fetchEmails(mailbox = 'INBOX', limit = 10, onlyUnread = false, page = 1) {
+  const client = createClient();
+  await client.connect();
+  const mb = await client.mailboxOpen(mailbox);
+  const total = mb.exists;
+  const emails = [];
+
+  if (total === 0) {
+    await client.logout();
+    return { emails, page, limit, total, totalPages: 0, hasMore: false };
+  }
+
+  if (onlyUnread) {
+    const uids = (await client.search({ seen: false }, { uid: true })) ?? [];
+    const totalUnread = uids.length;
+    const skip = (page - 1) * limit;
+    const pageUids = uids.reverse().slice(skip, skip + limit);
+    for (const uid of pageUids) {
+      const msg = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
+      if (msg) {
+        emails.push({
+          uid,
+          subject: msg.envelope.subject,
+          from: msg.envelope.from?.[0]?.address,
+          date: msg.envelope.date,
+          flagged: msg.flags.has('\\Flagged'),
+          seen: msg.flags.has('\\Seen')
+        });
+      }
+    }
+    await client.logout();
+    return { emails, page, limit, total: totalUnread, totalPages: Math.ceil(totalUnread / limit), hasMore: (page * limit) < totalUnread };
+  }
+
+  const end = Math.max(1, total - ((page - 1) * limit));
+  const start = Math.max(1, end - limit + 1);
+  const range = `${start}:${end}`;
+
+  for await (const msg of client.fetch(range, { envelope: true, flags: true })) {
+    emails.push({
+      uid: msg.uid,
+      subject: msg.envelope.subject,
+      from: msg.envelope.from?.[0]?.address,
+      date: msg.envelope.date,
+      flagged: msg.flags.has('\\Flagged'),
+      seen: msg.flags.has('\\Seen')
+    });
+  }
+
+  await client.logout();
+  emails.reverse();
+  return { emails, page, limit, total, totalPages: Math.ceil(total / limit), hasMore: (page * limit) < total };
+}
+
+async function getInboxSummary(mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  const status = await client.status(mailbox, { messages: true, unseen: true, recent: true });
+  await client.logout();
+  return { mailbox, total: status.messages, unread: status.unseen, recent: status.recent };
+}
+
+async function getTopSenders(mailbox = 'INBOX', sampleSize = 500) {
+  const client = createClient();
+  await client.connect();
+  const mb = await client.mailboxOpen(mailbox);
+  const total = mb.exists;
+  const senderCounts = {};
+  const senderDomains = {};
+
+  const end = total;
+  const start = Math.max(1, total - sampleSize + 1);
+  const range = `${start}:${end}`;
+  let count = 0;
+
+  for await (const msg of client.fetch(range, { envelope: true })) {
+    const address = msg.envelope.from?.[0]?.address;
+    if (address) {
+      senderCounts[address] = (senderCounts[address] || 0) + 1;
+      const domain = address.split('@')[1];
+      if (domain) senderDomains[domain] = (senderDomains[domain] || 0) + 1;
+    }
+    count++;
+  }
+
+  await client.logout();
+  const topAddresses = Object.entries(senderCounts).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([address, count]) => ({ address, count }));
+  const topDomains = Object.entries(senderDomains).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([domain, count]) => ({ domain, count }));
+  return { sampledEmails: count, topAddresses, topDomains };
+}
+
+async function getUnreadSenders(mailbox = 'INBOX', sampleSize = 500) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search({ seen: false }, { uid: true })) ?? [];
+  const recentUids = uids.reverse().slice(0, sampleSize);
+  const senderCounts = {};
+
+  for (const uid of recentUids) {
+    const msg = await client.fetchOne(uid, { envelope: true }, { uid: true });
+    if (msg) {
+      const address = msg.envelope.from?.[0]?.address;
+      if (address) senderCounts[address] = (senderCounts[address] || 0) + 1;
+    }
+  }
+
+  await client.logout();
+  return Object.entries(senderCounts).sort((a, b) => b[1] - a[1]).slice(0, 20).map(([address, count]) => ({ address, count }));
+}
+
+async function getEmailsBySender(sender, mailbox = 'INBOX', limit = 10) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
+  const total = uids.length;
+  const recentUids = uids.slice(-limit).reverse();
+  const emails = [];
+  for (const uid of recentUids) {
+    const msg = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
+    if (msg) {
+      emails.push({
+        uid,
+        subject: msg.envelope.subject,
+        from: msg.envelope.from?.[0]?.address,
+        date: msg.envelope.date,
+        flagged: msg.flags.has('\\Flagged'),
+        seen: msg.flags.has('\\Seen')
+      });
+    }
+  }
+  await client.logout();
+  return { total, showing: emails.length, emails };
+}
+
+async function bulkDeleteBySender(sender, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
+  await client.messageDelete(uids, { uid: true });
+  await client.logout();
+  return { deleted: uids.length, sender };
+}
+
+async function bulkMoveBySender(sender, targetMailbox, sourceMailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(sourceMailbox);
+  const uids = (await client.search({ from: sender }, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { moved: 0 }; }
+  await client.messageMove(uids, targetMailbox, { uid: true });
+  await client.logout();
+  return { moved: uids.length, sender, targetMailbox };
+}
+
+async function bulkDeleteBySubject(subject, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search({ subject }, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
+  await client.messageDelete(uids, { uid: true });
+  await client.logout();
+  return { deleted: uids.length, subject };
+}
+
+async function deleteOlderThan(days, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const date = new Date();
+  date.setDate(date.getDate() - days);
+  const uids = (await client.search({ before: date }, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
+  await client.messageDelete(uids, { uid: true });
+  await client.logout();
+  return { deleted: uids.length, olderThan: date.toISOString() };
+}
+
+async function getEmailsByDateRange(startDate, endDate, mailbox = 'INBOX', limit = 10) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search({ since: new Date(startDate), before: new Date(endDate) }, { uid: true })) ?? [];
+  const total = uids.length;
+  const recentUids = uids.slice(-limit).reverse();
+  const emails = [];
+  for (const uid of recentUids) {
+    const msg = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
+    if (msg) {
+      emails.push({
+        uid,
+        subject: msg.envelope.subject,
+        from: msg.envelope.from?.[0]?.address,
+        date: msg.envelope.date,
+        flagged: msg.flags.has('\\Flagged'),
+        seen: msg.flags.has('\\Seen')
+      });
+    }
+  }
+  await client.logout();
+  return { total, showing: emails.length, emails };
+}
+
+async function bulkMarkRead(mailbox = 'INBOX', sender = null) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const query = sender ? { from: sender, seen: false } : { seen: false };
+  const uids = (await client.search(query, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { marked: 0 }; }
+  await client.messageFlagsAdd(uids, ['\\Seen'], { uid: true });
+  await client.logout();
+  return { marked: uids.length, sender: sender || 'all' };
+}
+
+async function emptyTrash() {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen('Deleted Messages');
+  const uids = (await client.search({ all: true }, { uid: true })) ?? [];
+  if (uids.length === 0) { await client.logout(); return { deleted: 0 }; }
+  await client.messageDelete(uids, { uid: true });
+  await client.logout();
+  return { deleted: uids.length };
+}
+
+async function createMailbox(name) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxCreate(name);
+  await client.logout();
+  return { created: name };
+}
+
+async function getEmailContent(uid, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const meta = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
+  let body = '(body unavailable)';
+  try {
+    const sourceMsg = await Promise.race([
+      client.fetchOne(uid, { source: true }, { uid: true }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 10000))
+    ]);
+    if (sourceMsg?.source) {
+      const raw = sourceMsg.source.toString();
+      const bodyStart = raw.indexOf('\r\n\r\n');
+      body = bodyStart > -1 ? raw.slice(bodyStart + 4, bodyStart + 2000) : raw.slice(0, 2000);
+    }
+  } catch {
+    body = '(body unavailable - email may be too large)';
+  }
+  await client.logout();
+  return {
+    uid: meta.uid,
+    subject: meta.envelope.subject,
+    from: meta.envelope.from?.[0]?.address,
+    date: meta.envelope.date,
+    flags: [...meta.flags],
+    body
+  };
+}
+
+async function flagEmail(uid, flagged, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  if (flagged) {
+    await client.messageFlagsAdd(uid, ['\\Flagged'], { uid: true });
+  } else {
+    await client.messageFlagsRemove(uid, ['\\Flagged'], { uid: true });
+  }
+  await client.logout();
+  return true;
+}
+
+async function markAsRead(uid, seen, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  if (seen) {
+    await client.messageFlagsAdd(uid, ['\\Seen'], { uid: true });
+  } else {
+    await client.messageFlagsRemove(uid, ['\\Seen'], { uid: true });
+  }
+  await client.logout();
+  return true;
+}
+
+async function deleteEmail(uid, mailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  await client.messageDelete(uid, { uid: true });
+  await client.logout();
+  return true;
+}
+
+async function listMailboxes() {
+  const client = createClient();
+  await client.connect();
+  const tree = await client.listTree();
+  const mailboxes = [];
+  function walk(items) {
+    for (const item of items) {
+      mailboxes.push({ name: item.name, path: item.path });
+      if (item.folders && item.folders.length > 0) walk(item.folders);
+    }
+  }
+  walk(tree.folders);
+  await client.logout();
+  return mailboxes;
+}
+
+async function searchEmails(query, mailbox = 'INBOX', limit = 10) {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(mailbox);
+  const uids = (await client.search(
+    { or: [{ subject: query }, { from: query }, { body: query }] },
+    { uid: true }
+  )) ?? [];
+  const emails = [];
+  const recentUids = uids.slice(-limit).reverse();
+  for (const uid of recentUids) {
+    const msg = await client.fetchOne(uid, { envelope: true, flags: true }, { uid: true });
+    if (msg) {
+      emails.push({
+        uid,
+        subject: msg.envelope.subject,
+        from: msg.envelope.from?.[0]?.address,
+        date: msg.envelope.date,
+        flagged: msg.flags.has('\\Flagged'),
+        seen: msg.flags.has('\\Seen')
+      });
+    }
+  }
+  await client.logout();
+  return emails;
+}
+
+async function moveEmail(uid, targetMailbox, sourceMailbox = 'INBOX') {
+  const client = createClient();
+  await client.connect();
+  await client.mailboxOpen(sourceMailbox);
+  await client.messageMove(uid, targetMailbox, { uid: true });
+  await client.logout();
+  return true;
+}
+
+async function main() {
+  const server = new Server(
+    { name: 'icloud-mail', version: '1.0.8' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: 'get_inbox_summary',
+        description: 'Get a summary of a mailbox including total, unread, and recent email counts',
+        inputSchema: { type: 'object', properties: { mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' } } }
+      },
+      {
+        name: 'get_top_senders',
+        description: 'Get the top senders by email count from a sample of the inbox',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mailbox: { type: 'string', description: 'Mailbox to analyze (default INBOX)' },
+            sampleSize: { type: 'number', description: 'Number of emails to sample (default 500)' }
+          }
+        }
+      },
+      {
+        name: 'get_unread_senders',
+        description: 'Get top senders of unread emails',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mailbox: { type: 'string', description: 'Mailbox to analyze (default INBOX)' },
+            sampleSize: { type: 'number', description: 'Number of emails to sample (default 500)' }
+          }
+        }
+      },
+      {
+        name: 'get_emails_by_sender',
+        description: 'Get all emails from a specific sender',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sender: { type: 'string', description: 'Sender email address or domain' },
+            mailbox: { type: 'string', description: 'Mailbox to search (default INBOX)' },
+            limit: { type: 'number', description: 'Max results to show (default 10)' }
+          },
+          required: ['sender']
+        }
+      },
+      {
+        name: 'read_inbox',
+        description: 'Read emails from iCloud inbox with pagination',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: { type: 'number', description: 'Number of emails per page (default 10)' },
+            page: { type: 'number', description: 'Page number (default 1)' },
+            onlyUnread: { type: 'boolean', description: 'Only fetch unread emails' },
+            mailbox: { type: 'string', description: 'Mailbox to read (default INBOX)' }
+          }
+        }
+      },
+      {
+        name: 'get_email',
+        description: 'Get full content of a specific email by UID',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID' },
+            mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' }
+          },
+          required: ['uid']
+        }
+      },
+      {
+        name: 'search_emails',
+        description: 'Search emails by keyword',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Search query' },
+            mailbox: { type: 'string', description: 'Mailbox to search (default INBOX)' },
+            limit: { type: 'number', description: 'Max results (default 10)' }
+          },
+          required: ['query']
+        }
+      },
+      {
+        name: 'bulk_delete_by_sender',
+        description: 'Delete all emails from a specific sender',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sender: { type: 'string', description: 'Sender email address' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' }
+          },
+          required: ['sender']
+        }
+      },
+      {
+        name: 'bulk_move_by_sender',
+        description: 'Move all emails from a specific sender to a folder',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            sender: { type: 'string', description: 'Sender email address' },
+            targetMailbox: { type: 'string', description: 'Destination folder' },
+            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' }
+          },
+          required: ['sender', 'targetMailbox']
+        }
+      },
+      {
+        name: 'bulk_delete_by_subject',
+        description: 'Delete all emails matching a subject pattern',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            subject: { type: 'string', description: 'Subject keyword to match' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' }
+          },
+          required: ['subject']
+        }
+      },
+      {
+        name: 'delete_older_than',
+        description: 'Delete all emails older than a certain number of days',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            days: { type: 'number', description: 'Delete emails older than this many days' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' }
+          },
+          required: ['days']
+        }
+      },
+      {
+        name: 'get_emails_by_date_range',
+        description: 'Get emails between two dates',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            startDate: { type: 'string', description: 'Start date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'End date (YYYY-MM-DD)' },
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
+            limit: { type: 'number', description: 'Max results (default 10)' }
+          },
+          required: ['startDate', 'endDate']
+        }
+      },
+      {
+        name: 'bulk_mark_read',
+        description: 'Mark all emails as read, optionally filtered by sender',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            mailbox: { type: 'string', description: 'Mailbox (default INBOX)' },
+            sender: { type: 'string', description: 'Optional: only mark emails from this sender as read' }
+          }
+        }
+      },
+      {
+        name: 'empty_trash',
+        description: 'Permanently delete all emails in Deleted Messages',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'create_mailbox',
+        description: 'Create a new mailbox/folder',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Name of the new mailbox' }
+          },
+          required: ['name']
+        }
+      },
+      {
+        name: 'flag_email',
+        description: 'Flag or unflag an email',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID' },
+            flagged: { type: 'boolean', description: 'True to flag, false to unflag' },
+            mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' }
+          },
+          required: ['uid', 'flagged']
+        }
+      },
+      {
+        name: 'mark_as_read',
+        description: 'Mark an email as read or unread',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID' },
+            seen: { type: 'boolean', description: 'True to mark as read, false for unread' },
+            mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' }
+          },
+          required: ['uid', 'seen']
+        }
+      },
+      {
+        name: 'delete_email',
+        description: 'Delete an email',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID' },
+            mailbox: { type: 'string', description: 'Mailbox name (default INBOX)' }
+          },
+          required: ['uid']
+        }
+      },
+      {
+        name: 'move_email',
+        description: 'Move an email to a different mailbox/folder',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: { type: 'number', description: 'Email UID' },
+            targetMailbox: { type: 'string', description: 'Destination mailbox path' },
+            sourceMailbox: { type: 'string', description: 'Source mailbox (default INBOX)' }
+          },
+          required: ['uid', 'targetMailbox']
+        }
+      },
+      {
+        name: 'list_mailboxes',
+        description: 'List all mailboxes/folders in iCloud Mail',
+        inputSchema: { type: 'object', properties: {} }
+      }
+    ]
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      let result;
+      if (name === 'get_inbox_summary') {
+        result = await getInboxSummary(args.mailbox || 'INBOX');
+      } else if (name === 'get_top_senders') {
+        result = await getTopSenders(args.mailbox || 'INBOX', args.sampleSize || 500);
+      } else if (name === 'get_unread_senders') {
+        result = await getUnreadSenders(args.mailbox || 'INBOX', args.sampleSize || 500);
+      } else if (name === 'get_emails_by_sender') {
+        result = await getEmailsBySender(args.sender, args.mailbox || 'INBOX', args.limit || 10);
+      } else if (name === 'read_inbox') {
+        result = await fetchEmails(args.mailbox || 'INBOX', args.limit || 10, args.onlyUnread || false, args.page || 1);
+      } else if (name === 'get_email') {
+        result = await getEmailContent(args.uid, args.mailbox || 'INBOX');
+      } else if (name === 'search_emails') {
+        result = await searchEmails(args.query, args.mailbox || 'INBOX', args.limit || 10);
+      } else if (name === 'bulk_delete_by_sender') {
+        result = await bulkDeleteBySender(args.sender, args.mailbox || 'INBOX');
+      } else if (name === 'bulk_move_by_sender') {
+        result = await bulkMoveBySender(args.sender, args.targetMailbox, args.sourceMailbox || 'INBOX');
+      } else if (name === 'bulk_delete_by_subject') {
+        result = await bulkDeleteBySubject(args.subject, args.mailbox || 'INBOX');
+      } else if (name === 'delete_older_than') {
+        result = await deleteOlderThan(args.days, args.mailbox || 'INBOX');
+      } else if (name === 'get_emails_by_date_range') {
+        result = await getEmailsByDateRange(args.startDate, args.endDate, args.mailbox || 'INBOX', args.limit || 10);
+      } else if (name === 'bulk_mark_read') {
+        result = await bulkMarkRead(args.mailbox || 'INBOX', args.sender || null);
+      } else if (name === 'empty_trash') {
+        result = await emptyTrash();
+      } else if (name === 'create_mailbox') {
+        result = await createMailbox(args.name);
+      } else if (name === 'flag_email') {
+        result = await flagEmail(args.uid, args.flagged, args.mailbox || 'INBOX');
+      } else if (name === 'mark_as_read') {
+        result = await markAsRead(args.uid, args.seen, args.mailbox || 'INBOX');
+      } else if (name === 'delete_email') {
+        result = await deleteEmail(args.uid, args.mailbox || 'INBOX');
+      } else if (name === 'move_email') {
+        result = await moveEmail(args.uid, args.targetMailbox, args.sourceMailbox || 'INBOX');
+      } else if (name === 'list_mailboxes') {
+        result = await listMailboxes();
+      } else {
+        throw new Error(`Unknown tool: ${name}`);
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('iCloud Mail MCP Server running\n');
+}
+
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`Uncaught exception: ${err.message}\n${err.stack}\n`);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`Unhandled rejection: ${reason}\n`);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  process.stderr.write(`Fatal error: ${err.message}\n${err.stack}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "icloud-mcp",
+  "version": "1.0.0",
+  "description": "A Model Context Protocol (MCP) server for iCloud Mail",
+  "main": "index.js",
+  "bin": {
+    "icloud-mcp": "./index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "test": "node test.js"
+  },
+  "keywords": ["mcp", "icloud", "email", "imap", "claude"],
+  "author": "Adam Zaidi",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "imapflow": "^1.2.10"
+  }
+}

package/test.js

@@ -0,0 +1,211 @@
+import { spawnSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+const IMAP_USER = process.env.IMAP_USER;
+const IMAP_PASSWORD = process.env.IMAP_PASSWORD;
+
+if (!IMAP_USER || !IMAP_PASSWORD) {
+  console.error('Error: IMAP_USER and IMAP_PASSWORD environment variables are required');
+  process.exit(1);
+}
+
+const projectDir = fileURLToPath(new URL('.', import.meta.url));
+
+function callTool(name, args = {}) {
+  const messages = [
+    { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'test', version: '1.0.0' } } },
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }
+  ];
+
+  const input = messages.map(m => JSON.stringify(m)).join('\n') + '\n';
+  const tmpFile = join(tmpdir(), `mcp-test-${Date.now()}.txt`);
+  writeFileSync(tmpFile, input);
+
+  try {
+    const result = spawnSync(
+      '/bin/sh',
+      ['-c', `cat "${tmpFile}" | /opt/homebrew/bin/node index.js`],
+      {
+        cwd: projectDir,
+        encoding: 'utf8',
+        timeout: 180000,
+        env: { ...process.env, IMAP_USER, IMAP_PASSWORD }
+      }
+    );
+
+    if (result.error) throw new Error(`Spawn error: ${result.error.message}`);
+    if (result.status !== 0) throw new Error(`Process exited with code ${result.status}: ${result.stderr}`);
+
+    const lines = (result.stdout || '').trim().split('\n').filter(l => l.trim().startsWith('{'));
+    const responses = lines.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+    const toolResponse = responses.find(r => r.id === 1);
+    if (!toolResponse) throw new Error(`No response for tool: ${name}`);
+    const content = toolResponse.result?.content?.[0]?.text;
+    if (!content) throw new Error(`No content in response for: ${name}`);
+    if (toolResponse.result?.isError) throw new Error(`Tool error: ${content}`);
+    return JSON.parse(content);
+  } finally {
+    try { unlinkSync(tmpFile); } catch {}
+  }
+}
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  process.stdout.write(`  Testing ${name}... `);
+  try {
+    fn();
+    console.log('✅ passed');
+    passed++;
+  } catch (err) {
+    console.log(`❌ failed: ${err.message}`);
+    failed++;
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+console.log('\n🧪 iCloud MCP Server Tests\n');
+
+console.log('📬 Mailbox & Summary');
+
+test('get_inbox_summary', () => {
+  const result = callTool('get_inbox_summary');
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(typeof result.unread === 'number', 'unread should be a number');
+  assert(result.mailbox === 'INBOX', 'mailbox should be INBOX');
+  console.log(`\n     → ${result.total} total, ${result.unread} unread`);
+});
+
+test('list_mailboxes', () => {
+  const result = callTool('list_mailboxes');
+  assert(Array.isArray(result), 'result should be an array');
+  assert(result.length > 0, 'should have at least one mailbox');
+  assert(result.some(m => m.path === 'INBOX'), 'INBOX should exist');
+  console.log(`\n     → ${result.length} mailboxes found`);
+});
+
+test('get_top_senders (sample 50)', () => {
+  const result = callTool('get_top_senders', { sampleSize: 50 });
+  assert(Array.isArray(result.topAddresses), 'topAddresses should be an array');
+  assert(Array.isArray(result.topDomains), 'topDomains should be an array');
+  assert(result.sampledEmails <= 50, 'should not exceed sample size');
+  console.log(`\n     → top sender: ${result.topAddresses[0]?.address} (${result.topAddresses[0]?.count})`);
+});
+
+test('get_unread_senders (sample 50)', () => {
+  const result = callTool('get_unread_senders', { sampleSize: 50 });
+  assert(Array.isArray(result), 'result should be an array');
+  console.log(`\n     → ${result.length} unread senders found`);
+});
+
+console.log('\n📧 Reading Emails');
+
+test('read_inbox (page 1, limit 5)', () => {
+  const result = callTool('read_inbox', { limit: 5, page: 1 });
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  assert(result.emails.length <= 5, 'should not exceed limit');
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(typeof result.hasMore === 'boolean', 'hasMore should be a boolean');
+  console.log(`\n     → ${result.emails.length} emails, ${result.total} total`);
+});
+
+test('read_inbox (page 2)', () => {
+  const p1 = callTool('read_inbox', { limit: 5, page: 1 });
+  const p2 = callTool('read_inbox', { limit: 5, page: 2 });
+  assert(Array.isArray(p2.emails), 'page 2 emails should be an array');
+  if (p1.emails.length > 0 && p2.emails.length > 0) {
+    assert(p1.emails[0].uid !== p2.emails[0].uid, 'pages should have different emails');
+  }
+  console.log(`\n     → page 2 has ${p2.emails.length} emails`);
+});
+
+test('read_inbox (unread only)', () => {
+  const result = callTool('read_inbox', { limit: 5, onlyUnread: true });
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  result.emails.forEach(e => assert(!e.seen, 'all emails should be unread'));
+  console.log(`\n     → ${result.emails.length} unread emails`);
+});
+
+test('search_emails', () => {
+  const result = callTool('search_emails', { query: 'test', limit: 5 });
+  assert(Array.isArray(result), 'result should be an array');
+  console.log(`\n     → ${result.length} results`);
+});
+
+test('get_emails_by_sender', () => {
+  const senders = callTool('get_top_senders', { sampleSize: 20 });
+  const topSender = senders.topAddresses[0]?.address;
+  assert(topSender, 'should have at least one sender');
+  const result = callTool('get_emails_by_sender', { sender: topSender, limit: 5 });
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  console.log(`\n     → ${result.total} emails from ${topSender}`);
+});
+
+test('get_emails_by_date_range', () => {
+  const result = callTool('get_emails_by_date_range', {
+    startDate: '2025-01-01',
+    endDate: '2025-12-31',
+    limit: 5
+  });
+  assert(typeof result.total === 'number', 'total should be a number');
+  assert(Array.isArray(result.emails), 'emails should be an array');
+  console.log(`\n     → ${result.total} emails in 2025`);
+});
+
+test('get_email (fetch first email content)', () => {
+  const inbox = callTool('read_inbox', { limit: 1 });
+  assert(inbox.emails.length > 0, 'inbox should have at least one email');
+  const uid = inbox.emails[0].uid;
+  const result = callTool('get_email', { uid });
+  assert(result.uid === uid, 'uid should match');
+  assert(typeof result.body === 'string', 'body should be a string');
+  console.log(`\n     → fetched email: "${result.subject?.slice(0, 40)}..."`);
+});
+
+console.log('\n✏️  Write Operations (flag/mark only — no deletions)');
+
+test('flag_email and unflag_email', () => {
+  const inbox = callTool('read_inbox', { limit: 1 });
+  assert(inbox.emails.length > 0, 'inbox should have at least one email');
+  const uid = inbox.emails[0].uid;
+  const flagResult = callTool('flag_email', { uid, flagged: true });
+  assert(flagResult === true, 'flag should return true');
+  const unflagResult = callTool('flag_email', { uid, flagged: false });
+  assert(unflagResult === true, 'unflag should return true');
+  console.log(`\n     → flagged and unflagged uid ${uid}`);
+});
+
+test('mark_as_read and mark_as_unread', () => {
+  const inbox = callTool('read_inbox', { limit: 1 });
+  assert(inbox.emails.length > 0, 'inbox should have at least one email');
+  const uid = inbox.emails[0].uid;
+  const readResult = callTool('mark_as_read', { uid, seen: true });
+  assert(readResult === true, 'mark read should return true');
+  const unreadResult = callTool('mark_as_read', { uid, seen: false });
+  assert(unreadResult === true, 'mark unread should return true');
+  console.log(`\n     → marked read/unread uid ${uid}`);
+});
+
+console.log('\n⚠️  Destructive Tests (skipped by default)');
+console.log('  Skipping: bulk_delete_by_sender');
+console.log('  Skipping: bulk_delete_by_subject');
+console.log('  Skipping: delete_older_than');
+console.log('  Skipping: delete_email');
+console.log('  Skipping: empty_trash');
+console.log('  Run with --destructive flag to enable these\n');
+
+console.log('─'.repeat(40));
+console.log(`\n✅ Passed: ${passed}`);
+console.log(`❌ Failed: ${failed}`);
+console.log(`📊 Total:  ${passed + failed}\n`);
+
+if (failed > 0) process.exit(1);