@sempervirens-labs/apple-mail-mcp 1.0.0 → 1.1.0

package/.claude/settings.local.json

@@ -7,7 +7,9 @@
       "WebFetch(domain:www.npmjs.com)",
       "Bash(bun install)",
       "Bash(osascript:*)",
-      "Bash(npm publish:*)"
+      "Bash(npm publish:*)",
+      "Bash(bun run build)",
+      "Bash(npx tsc:*)"
     ]
   }
 }

package/README.md

@@ -10,6 +10,11 @@ An MCP (Model Context Protocol) server for Apple Mail on macOS. Allows AI assist
 - **Search Emails** - Search by subject, sender, or content
 - **Unread Count** - Get unread email counts
 - **Send Email** - Compose and send emails with CC/BCC support
+- **Archive Email** - Move emails to the Archive mailbox
+- **Delete Email** - Move emails to Trash
+- **Mark as Read/Unread** - Change read status of emails
+- **Create Draft** - Create new draft emails
+- **Create Draft Reply** - Create draft replies to existing emails
 
 ## Requirements
 
@@ -19,18 +24,22 @@ An MCP (Model Context Protocol) server for Apple Mail on macOS. Allows AI assist
 
 ## Installation
 
-### From Source
+### From npm (Recommended)
 
 ```bash
-git clone https://github.com/yourusername/apple-mail-mcp.git
-cd apple-mail-mcp
-bun install
+# Install globally
+bun add -g @sempervirens-labs/apple-mail-mcp
+
+# Or run directly without installation
+bunx @sempervirens-labs/apple-mail-mcp
 ```
 
-### Using bunx (no installation required)
+### From Source
 
 ```bash
-bunx @sempervirens-labs/apple-mail-mcp
+git clone https://github.com/rbouschery/apple-mail-mcp.git
+cd apple-mail-mcp
+bun install
 ```
 
 ## Configuration
@@ -43,21 +52,21 @@ Add to your `~/.claude/settings.json`:
 {
   "mcpServers": {
     "apple-mail": {
-      "command": "bun",
-      "args": ["run", "/path/to/apple-mail-mcp/src/index.ts"]
+      "command": "bunx",
+      "args": ["@sempervirens-labs/apple-mail-mcp"]
     }
   }
 }
 ```
 
-Or if published to npm:
+Or if running from source:
 
 ```json
 {
   "mcpServers": {
     "apple-mail": {
-      "command": "bunx",
-      "args": ["apple-mail-mcp"]
+      "command": "bun",
+      "args": ["run", "/path/to/apple-mail-mcp/src/index.ts"]
     }
   }
 }
@@ -73,8 +82,8 @@ Add to your Cursor MCP settings (Settings > MCP Servers):
 {
   "mcpServers": {
     "apple-mail": {
-      "command": "bun",
-      "args": ["run", "/path/to/apple-mail-mcp/src/index.ts"]
+      "command": "bunx",
+      "args": ["@sempervirens-labs/apple-mail-mcp"]
     }
   }
 }
@@ -86,8 +95,8 @@ Or via Cursor's settings UI:
 3. Click "Add Server"
 4. Enter:
    - **Name**: `apple-mail`
-   - **Command**: `bun`
-   - **Arguments**: `run`, `/path/to/apple-mail-mcp/src/index.ts`
+   - **Command**: `bunx`
+   - **Arguments**: `@sempervirens-labs/apple-mail-mcp`
 
 ### Claude Desktop
 
@@ -97,8 +106,8 @@ Add to your `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "apple-mail": {
-      "command": "bun",
-      "args": ["run", "/path/to/apple-mail-mcp/src/index.ts"]
+      "command": "bunx",
+      "args": ["@sempervirens-labs/apple-mail-mcp"]
     }
   }
 }
@@ -216,6 +225,119 @@ Send an email using Apple Mail.
 }
 ```
 
+### `mail_archive`
+
+Archive an email by moving it to the Archive mailbox.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | number | **Yes** | - | Email ID (from mail_get_emails or mail_search) |
+| `account` | string | No | - | Account name |
+| `mailbox` | string | No | "INBOX" | Current mailbox of the email |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Message archived successfully"
+}
+```
+
+### `mail_delete`
+
+Delete an email by moving it to Trash.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | number | **Yes** | - | Email ID (from mail_get_emails or mail_search) |
+| `account` | string | No | - | Account name |
+| `mailbox` | string | No | "INBOX" | Current mailbox of the email |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Message deleted successfully"
+}
+```
+
+### `mail_mark_read`
+
+Mark an email as read.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | number | **Yes** | - | Email ID (from mail_get_emails or mail_search) |
+| `account` | string | No | - | Account name |
+| `mailbox` | string | No | "INBOX" | Mailbox where the email is located |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Message marked as read"
+}
+```
+
+### `mail_mark_unread`
+
+Mark an email as unread.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | number | **Yes** | - | Email ID (from mail_get_emails or mail_search) |
+| `account` | string | No | - | Account name |
+| `mailbox` | string | No | "INBOX" | Mailbox where the email is located |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Message marked as unread"
+}
+```
+
+### `mail_create_draft`
+
+Create a new draft email.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `to` | string or string[] | No | Recipient email(s) |
+| `subject` | string | **Yes** | Email subject |
+| `body` | string | **Yes** | Email body |
+| `cc` | string or string[] | No | CC recipient(s) |
+| `bcc` | string or string[] | No | BCC recipient(s) |
+| `from` | string | No | Sender (must be configured account) |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Draft created successfully"
+}
+```
+
+### `mail_create_draft_reply`
+
+Create a draft reply to an existing email.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `messageId` | number | **Yes** | - | Email ID to reply to (from mail_get_emails or mail_search) |
+| `body` | string | **Yes** | - | Reply body content |
+| `replyAll` | boolean | No | false | Reply to all recipients |
+| `account` | string | No | - | Account name |
+| `mailbox` | string | No | "INBOX" | Mailbox where the original email is located |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "message": "Draft reply created successfully"
+}
+```
+
 ## Permissions
 
 On first use, macOS will prompt you to grant permissions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sempervirens-labs/apple-mail-mcp",
-  "version": "1.0.0",
+  "version": "1.1.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

@@ -354,3 +354,263 @@ end tell
     return { success: false, message: error.message };
   }
 }
+
+/**
+ * Archive an email by moving it to the Archive mailbox
+ */
+export function archiveEmail(options: {
+  messageId: number;
+  account?: string;
+  mailbox?: string;
+}): { success: boolean; message: string } {
+  const { messageId, account, mailbox = "INBOX" } = options;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  const script = `
+tell application "Mail"
+    try
+        set theMailbox to ${accountPart}
+        set theMessage to (first message of theMailbox whose id is ${messageId})
+        set theAccount to account of theMailbox
+
+        -- Find the Archive mailbox for this account
+        set archiveMailbox to missing value
+        repeat with mb in mailboxes of theAccount
+            if name of mb is "Archive" or name of mb is "All Mail" then
+                set archiveMailbox to mb
+                exit repeat
+            end if
+        end repeat
+
+        if archiveMailbox is missing value then
+            return "ERROR:No Archive mailbox found for this account"
+        end if
+
+        move theMessage to archiveMailbox
+        return "Message archived successfully"
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    if (result.startsWith("ERROR:")) {
+      return { success: false, message: result.substring(6) };
+    }
+    return { success: true, message: result || "Message archived successfully" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}
+
+/**
+ * Delete an email by moving it to the Trash mailbox
+ */
+export function deleteEmail(options: {
+  messageId: number;
+  account?: string;
+  mailbox?: string;
+}): { success: boolean; message: string } {
+  const { messageId, account, mailbox = "INBOX" } = options;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  const script = `
+tell application "Mail"
+    try
+        set theMailbox to ${accountPart}
+        set theMessage to (first message of theMailbox whose id is ${messageId})
+        delete theMessage
+        return "Message deleted successfully"
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    if (result.startsWith("ERROR:")) {
+      return { success: false, message: result.substring(6) };
+    }
+    return { success: true, message: result || "Message deleted successfully" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}
+
+/**
+ * Mark an email as read
+ */
+export function markAsRead(options: {
+  messageId: number;
+  account?: string;
+  mailbox?: string;
+}): { success: boolean; message: string } {
+  const { messageId, account, mailbox = "INBOX" } = options;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  const script = `
+tell application "Mail"
+    try
+        set theMailbox to ${accountPart}
+        set theMessage to (first message of theMailbox whose id is ${messageId})
+        set read status of theMessage to true
+        return "Message marked as read"
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    if (result.startsWith("ERROR:")) {
+      return { success: false, message: result.substring(6) };
+    }
+    return { success: true, message: result || "Message marked as read" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}
+
+/**
+ * Mark an email as unread
+ */
+export function markAsUnread(options: {
+  messageId: number;
+  account?: string;
+  mailbox?: string;
+}): { success: boolean; message: string } {
+  const { messageId, account, mailbox = "INBOX" } = options;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  const script = `
+tell application "Mail"
+    try
+        set theMailbox to ${accountPart}
+        set theMessage to (first message of theMailbox whose id is ${messageId})
+        set read status of theMessage to false
+        return "Message marked as unread"
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    if (result.startsWith("ERROR:")) {
+      return { success: false, message: result.substring(6) };
+    }
+    return { success: true, message: result || "Message marked as unread" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}
+
+/**
+ * Create a draft email
+ */
+export function createDraft(options: {
+  to?: string | string[];
+  subject: string;
+  body: string;
+  cc?: string | string[];
+  bcc?: string | string[];
+  from?: string;
+}): { success: boolean; message: string } {
+  const { to, subject, body, cc, bcc, from } = options;
+
+  const toList = to ? (Array.isArray(to) ? to : [to]) : [];
+  const ccList = cc ? (Array.isArray(cc) ? cc : [cc]) : [];
+  const bccList = bcc ? (Array.isArray(bcc) ? bcc : [bcc]) : [];
+
+  // Build recipient parts
+  const toRecipients = toList.map(addr => `make new to recipient at end of to recipients with properties {address:"${addr}"}`).join("\n            ");
+  const ccRecipients = ccList.map(addr => `make new cc recipient at end of cc recipients with properties {address:"${addr}"}`).join("\n            ");
+  const bccRecipients = bccList.map(addr => `make new bcc recipient at end of bcc recipients with properties {address:"${addr}"}`).join("\n            ");
+
+  const fromPart = from ? `, sender:"${from}"` : "";
+
+  const script = `
+tell application "Mail"
+    set newMessage to make new outgoing message with properties {subject:"${subject.replace(/"/g, '\\"')}", content:"${body.replace(/"/g, '\\"').replace(/\n/g, "\\n")}", visible:true${fromPart}}
+    tell newMessage
+        ${toRecipients}
+        ${ccRecipients ? ccRecipients : ""}
+        ${bccRecipients ? bccRecipients : ""}
+    end tell
+    -- Save as draft by not sending, just leaving it open
+    return "Draft created successfully"
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    return { success: true, message: result || "Draft created successfully" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}
+
+/**
+ * Create a draft reply to an existing email
+ */
+export function createDraftReply(options: {
+  messageId: number;
+  body: string;
+  replyAll?: boolean;
+  account?: string;
+  mailbox?: string;
+}): { success: boolean; message: string } {
+  const { messageId, body, replyAll = false, account, mailbox = "INBOX" } = options;
+
+  const accountPart = account
+    ? `mailbox "${mailbox}" of account "${account}"`
+    : `mailbox "${mailbox}"`;
+
+  const replyCommand = replyAll ? "reply theMessage with opening window and reply to all" : "reply theMessage with opening window";
+
+  const script = `
+tell application "Mail"
+    try
+        set theMailbox to ${accountPart}
+        set theMessage to (first message of theMailbox whose id is ${messageId})
+
+        set replyMessage to ${replyCommand}
+
+        -- Prepend the new body to the reply
+        set currentContent to content of replyMessage
+        set content of replyMessage to "${body.replace(/"/g, '\\"').replace(/\n/g, "\\n")}" & return & return & currentContent
+
+        return "Draft reply created successfully"
+    on error errMsg
+        return "ERROR:" & errMsg
+    end try
+end tell
+`;
+
+  try {
+    const result = runAppleScript(script);
+    if (result.startsWith("ERROR:")) {
+      return { success: false, message: result.substring(6) };
+    }
+    return { success: true, message: result || "Draft reply created successfully" };
+  } catch (error: any) {
+    return { success: false, message: error.message };
+  }
+}

package/src/index.ts

@@ -15,6 +15,12 @@ import {
   searchEmails,
   getUnreadCount,
   sendEmail,
+  archiveEmail,
+  deleteEmail,
+  markAsRead,
+  markAsUnread,
+  createDraft,
+  createDraftReply,
 } from "./applescript/mail.js";
 
 // Create MCP server
@@ -147,6 +153,147 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case "mail_archive": {
+        const messageId = args?.messageId as number;
+        if (!messageId) {
+          throw new Error("Required field: messageId");
+        }
+
+        const result = archiveEmail({
+          messageId,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "mail_delete": {
+        const messageId = args?.messageId as number;
+        if (!messageId) {
+          throw new Error("Required field: messageId");
+        }
+
+        const result = deleteEmail({
+          messageId,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "mail_mark_read": {
+        const messageId = args?.messageId as number;
+        if (!messageId) {
+          throw new Error("Required field: messageId");
+        }
+
+        const result = markAsRead({
+          messageId,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "mail_mark_unread": {
+        const messageId = args?.messageId as number;
+        if (!messageId) {
+          throw new Error("Required field: messageId");
+        }
+
+        const result = markAsUnread({
+          messageId,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "mail_create_draft": {
+        const subject = args?.subject as string;
+        const body = args?.body as string;
+
+        if (!subject || !body) {
+          throw new Error("Required fields: subject, body");
+        }
+
+        const result = createDraft({
+          to: args?.to as string | string[] | undefined,
+          subject,
+          body,
+          cc: args?.cc as string | string[] | undefined,
+          bcc: args?.bcc as string | string[] | undefined,
+          from: args?.from as string | undefined,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "mail_create_draft_reply": {
+        const messageId = args?.messageId as number;
+        const body = args?.body as string;
+
+        if (!messageId || !body) {
+          throw new Error("Required fields: messageId, body");
+        }
+
+        const result = createDraftReply({
+          messageId,
+          body,
+          replyAll: (args?.replyAll as boolean) || false,
+          account: args?.account as string | undefined,
+          mailbox: (args?.mailbox as string) || "INBOX",
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/src/tools.ts

@@ -146,6 +146,179 @@ export const MAIL_SEND: Tool = {
   },
 };
 
+export const MAIL_ARCHIVE: Tool = {
+  name: "mail_archive",
+  description: "Archive an email in Apple Mail by moving it to the Archive mailbox",
+  inputSchema: {
+    type: "object",
+    properties: {
+      messageId: {
+        type: "number",
+        description: "The ID of the email message to archive (obtained from mail_get_emails or mail_search)",
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the email currently is (default: INBOX)",
+        default: "INBOX",
+      },
+    },
+    required: ["messageId"],
+  },
+};
+
+export const MAIL_DELETE: Tool = {
+  name: "mail_delete",
+  description: "Delete an email in Apple Mail by moving it to the Trash mailbox",
+  inputSchema: {
+    type: "object",
+    properties: {
+      messageId: {
+        type: "number",
+        description: "The ID of the email message to delete (obtained from mail_get_emails or mail_search)",
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the email currently is (default: INBOX)",
+        default: "INBOX",
+      },
+    },
+    required: ["messageId"],
+  },
+};
+
+export const MAIL_MARK_READ: Tool = {
+  name: "mail_mark_read",
+  description: "Mark an email as read in Apple Mail",
+  inputSchema: {
+    type: "object",
+    properties: {
+      messageId: {
+        type: "number",
+        description: "The ID of the email message to mark as read (obtained from mail_get_emails or mail_search)",
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the email is (default: INBOX)",
+        default: "INBOX",
+      },
+    },
+    required: ["messageId"],
+  },
+};
+
+export const MAIL_MARK_UNREAD: Tool = {
+  name: "mail_mark_unread",
+  description: "Mark an email as unread in Apple Mail",
+  inputSchema: {
+    type: "object",
+    properties: {
+      messageId: {
+        type: "number",
+        description: "The ID of the email message to mark as unread (obtained from mail_get_emails or mail_search)",
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the email is (default: INBOX)",
+        default: "INBOX",
+      },
+    },
+    required: ["messageId"],
+  },
+};
+
+export const MAIL_CREATE_DRAFT: Tool = {
+  name: "mail_create_draft",
+  description: "Create a new draft email in Apple Mail",
+  inputSchema: {
+    type: "object",
+    properties: {
+      to: {
+        oneOf: [
+          { type: "string" },
+          { type: "array", items: { type: "string" } },
+        ],
+        description: "Email address(es) of the recipient(s)",
+      },
+      subject: {
+        type: "string",
+        description: "The email subject line",
+      },
+      body: {
+        type: "string",
+        description: "The email body content",
+      },
+      cc: {
+        oneOf: [
+          { type: "string" },
+          { type: "array", items: { type: "string" } },
+        ],
+        description: "Email address(es) for CC recipients",
+      },
+      bcc: {
+        oneOf: [
+          { type: "string" },
+          { type: "array", items: { type: "string" } },
+        ],
+        description: "Email address(es) for BCC recipients",
+      },
+      from: {
+        type: "string",
+        description: "The sender email address (must be a configured account)",
+      },
+    },
+    required: ["subject", "body"],
+  },
+};
+
+export const MAIL_CREATE_DRAFT_REPLY: Tool = {
+  name: "mail_create_draft_reply",
+  description: "Create a draft reply to an existing email in Apple Mail",
+  inputSchema: {
+    type: "object",
+    properties: {
+      messageId: {
+        type: "number",
+        description: "The ID of the email message to reply to (obtained from mail_get_emails or mail_search)",
+      },
+      body: {
+        type: "string",
+        description: "The reply body content",
+      },
+      replyAll: {
+        type: "boolean",
+        description: "Whether to reply to all recipients (default: false)",
+        default: false,
+      },
+      account: {
+        type: "string",
+        description: "The name of the email account",
+      },
+      mailbox: {
+        type: "string",
+        description: "The name of the mailbox/folder where the original email is (default: INBOX)",
+        default: "INBOX",
+      },
+    },
+    required: ["messageId", "body"],
+  },
+};
+
 export const tools: Tool[] = [
   MAIL_LIST_ACCOUNTS,
   MAIL_LIST_MAILBOXES,
@@ -153,4 +326,10 @@ export const tools: Tool[] = [
   MAIL_SEARCH,
   MAIL_GET_UNREAD_COUNT,
   MAIL_SEND,
+  MAIL_ARCHIVE,
+  MAIL_DELETE,
+  MAIL_MARK_READ,
+  MAIL_MARK_UNREAD,
+  MAIL_CREATE_DRAFT,
+  MAIL_CREATE_DRAFT_REPLY,
 ];