@sempervirens-labs/apple-mail-mcp 1.4.1 → 1.5.0

package/README.md

@@ -181,6 +181,57 @@ Get recent emails from a mailbox.
 }
 ```
 
+### `mail_get_emails_by_ids`
+
+Get specific emails by their IDs. Useful for retrieving full details of specific emails after browsing with `mail_get_emails` (with `includeContent: false`).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `ids` | number[] | **Yes** | - | Array of email IDs to retrieve |
+| `account` | string | No | - | Account name (helps optimize search) |
+| `mailbox` | string | No | "INBOX" | Mailbox name (helps optimize search) |
+| `includeContent` | boolean | No | true | Include email body |
+
+**Example usage:**
+```json
+{
+  "ids": [12345, 67890],
+  "includeContent": true
+}
+```
+
+**Example response:**
+```json
+{
+  "emails": [
+    {
+      "id": 12345,
+      "subject": "Meeting tomorrow",
+      "sender": "John Doe <john@example.com>",
+      "to": ["you@example.com"],
+      "cc": [],
+      "bcc": [],
+      "dateSent": "Monday, 10. January 2025 at 09:30:00",
+      "isRead": false,
+      "content": "Let's meet at 2pm to discuss the project..."
+    },
+    {
+      "id": 67890,
+      "subject": "Project update",
+      "sender": "Jane Smith <jane@example.com>",
+      "to": ["you@example.com"],
+      "cc": [],
+      "bcc": [],
+      "dateSent": "Tuesday, 11. January 2025 at 14:15:00",
+      "isRead": true,
+      "content": "The project is progressing well..."
+    }
+  ],
+  "count": 2,
+  "requestedIds": [12345, 67890]
+}
+```
+
 ### `mail_search`
 
 Search emails by subject, sender, or content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sempervirens-labs/apple-mail-mcp",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "MCP server for Apple Mail - list accounts, mailboxes, search emails, and send messages",
   "type": "module",
   "main": "src/index.ts",

package/src/applescript/mail.ts

@@ -207,6 +207,108 @@ end tell
   return emails;
 }
 
+/**
+ * Get specific emails by their IDs
+ */
+export function getEmailsByIds(options: {
+  ids: number[];
+  account?: string;
+  mailbox?: string;
+  includeContent?: boolean;
+}): Email[] {
+  const { ids, account, mailbox = "INBOX", includeContent = true } = options;
+
+  if (!ids || ids.length === 0) {
+    return [];
+  }
+
+  const contentPart = includeContent
+    ? `set msgContent to content of msg`
+    : `set msgContent to ""`;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  // Build the ID list for AppleScript
+  const idList = ids.join(", ");
+
+  const script = `
+tell application "Mail"
+    set results to ""
+    set targetIds to {${idList}}
+    try
+        set theMailbox to ${accountPart}
+        set allMessages to messages of theMailbox
+
+        repeat with targetId in targetIds
+            repeat with msg in allMessages
+                if id of msg is targetId then
+                    set msgId to id of msg
+                    set msgSubject to subject of msg
+                    set msgSender to sender of msg
+                    set msgDate to date sent of msg
+                    set msgRead to read status of msg
+                    ${contentPart}
+
+                    -- Get recipients
+                    set toList to ""
+                    repeat with r in to recipients of msg
+                        set toList to toList & address of r & ","
+                    end repeat
+                    if toList is not "" then set toList to text 1 thru -2 of toList
+
+                    set ccList to ""
+                    repeat with r in cc recipients of msg
+                        set ccList to ccList & address of r & ","
+                    end repeat
+                    if ccList is not "" then set ccList to text 1 thru -2 of ccList
+
+                    set bccList to ""
+                    repeat with r in bcc recipients of msg
+                        set bccList to bccList & address of r & ","
+                    end repeat
+                    if bccList is not "" then set bccList to text 1 thru -2 of bccList
+
+                    set results to results & msgId & "<<>>" & msgSubject & "<<>>" & msgSender & "<<>>" & toList & "<<>>" & ccList & "<<>>" & bccList & "<<>>" & (msgDate as string) & "<<>>" & msgRead & "<<>>" & msgContent & "|||"
+                    exit repeat -- Found the message, move to next ID
+                end if
+            end repeat
+        end repeat
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+    return results
+end tell
+`;
+
+  const result = runAppleScript(script);
+
+  if (result.startsWith("ERROR:")) {
+    throw new Error(result.substring(6));
+  }
+
+  const emails: Email[] = [];
+  const parts = result.split("|||").filter(Boolean);
+
+  for (const part of parts) {
+    const [id, subject, sender, to, cc, bcc, dateSent, isRead, content] = part.split("<<>>");
+    emails.push({
+      id: parseInt(id) || 0,
+      subject: subject || "(No Subject)",
+      sender: sender || "(Unknown)",
+      to: to ? to.split(",").map(s => s.trim()).filter(Boolean) : [],
+      cc: cc ? cc.split(",").map(s => s.trim()).filter(Boolean) : [],
+      bcc: bcc ? bcc.split(",").map(s => s.trim()).filter(Boolean) : [],
+      dateSent: dateSent || "",
+      isRead: isRead === "true",
+      content: content || undefined,
+    });
+  }
+
+  return emails;
+}
+
 /**
  * Search emails by query
  */

package/src/index.ts

@@ -12,6 +12,7 @@ import {
   listAccounts,
   listMailboxes,
   getEmails,
+  getEmailsByIds,
   searchEmails,
   getUnreadCount,
   sendEmail,
@@ -90,6 +91,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case "mail_get_emails_by_ids": {
+        const ids = args?.ids as number[];
+        if (!ids || !Array.isArray(ids) || ids.length === 0) {
+          throw new Error("Required field: ids (must be a non-empty array of email IDs)");
+        }
+        const emails = getEmailsByIds({
+          ids,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+          includeContent: (args?.includeContent as boolean) ?? true,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ emails, count: emails.length, requestedIds: ids }, null, 2),
+            },
+          ],
+        };
+      }
+
       case "mail_search": {
         const query = args?.query as string;
         if (!query) {

package/src/tools.ts

@@ -60,6 +60,38 @@ export const MAIL_GET_EMAILS: Tool = {
   },
 };
 
+export const MAIL_GET_EMAILS_BY_IDS: Tool = {
+  name: "mail_get_emails_by_ids",
+  description: "Get specific emails by their IDs in Apple Mail. Use this to retrieve full details of specific emails after browsing with mail_get_emails (includeContent: false).",
+  inputSchema: {
+    type: "object",
+    properties: {
+      ids: {
+        type: "array",
+        items: {
+          type: "number",
+        },
+        description: "Array of email IDs to retrieve (obtained from mail_get_emails or mail_search)",
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account (helps optimize search)",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the emails are located (default: INBOX, helps optimize search)",
+        default: "INBOX",
+      },
+      includeContent: {
+        type: "boolean",
+        description: "Whether to include the email body content (default: true)",
+        default: true,
+      },
+    },
+    required: ["ids"],
+  },
+};
+
 export const MAIL_SEARCH: Tool = {
   name: "mail_search",
   description: "Search emails in Apple Mail by subject, sender, or content",
@@ -332,6 +364,7 @@ export const tools: Tool[] = [
   MAIL_LIST_ACCOUNTS,
   MAIL_LIST_MAILBOXES,
   MAIL_GET_EMAILS,
+  MAIL_GET_EMAILS_BY_IDS,
   MAIL_SEARCH,
   MAIL_GET_UNREAD_COUNT,
   MAIL_SEND,