apple-mail-mcp 1.6.9 → 1.7.0

package/README.md

@@ -270,6 +270,43 @@ Then send:
 
 The default `applescript` transport is unchanged; SMTP is opt-in per call.
 
+##### IMAP backend (read/search) — opt-in, Phase 1
+
+AppleScript runs `search`/`list` predicates client-side over the Apple Event
+bridge, which is slow and can time out (false-empty) on large Gmail/IMAP
+mailboxes (see [#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)). When
+an account is configured for IMAP, `search-messages` and `list-messages` instead
+run a **server-side IMAP search** ([#43](https://github.com/sweetrb/apple-mail-mcp/issues/43)) —
+typically sub-second and correct on the same mailbox where AppleScript times out.
+This is **opt-in and additive**: any account without IMAP configured behaves
+exactly as before (AppleScript). Read-only for now — `get-message` and all
+mutations stay on AppleScript (the IMAP rows report message **UIDs**, noted in
+the output).
+
+Routing is conservative: only a call whose explicit `account` matches the
+configured IMAP account goes to IMAP; everything else falls through to
+AppleScript.
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `APPLE_MAIL_MCP_IMAP_USER` | Yes | — | Login address; setting it enables IMAP |
+| `APPLE_MAIL_MCP_IMAP_ACCOUNT` | No | = user | Mail account name to match for routing |
+| `APPLE_MAIL_MCP_IMAP_HOST` | No | `imap.gmail.com` | IMAP server hostname |
+| `APPLE_MAIL_MCP_IMAP_PORT` | No | `993` | IMAP port (993 = implicit TLS) |
+| `APPLE_MAIL_MCP_IMAP_PASSWORD` | No | — | Password (if set, used instead of the Keychain) |
+| `APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE` | No | — | Keychain item service/server name |
+| `APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT` | No | = user | Keychain item account |
+
+As with SMTP, the password is read from the macOS **Keychain** by default (use
+an app-specific password for Gmail/Workspace/iCloud), so no secret goes in
+config. Gmail label semantics: common names (`All Mail`, `Sent`, `Trash`,
+`Spam`, `Important`, …) map to their `[Gmail]/…` IMAP paths automatically.
+
+> Note: each call currently opens its own IMAP connection (no pooling yet), so
+> expect a few seconds of connection overhead per call. Phase 2 (IMAP-backed
+> mutations + folder ops, which would also resolve the IMAP slice of
+> [#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) is not yet implemented.
+
 ---
 
 #### `send-serial-email`
@@ -800,6 +837,7 @@ The entrypoint is written as:
 | Attachments require absolute paths | File attachments must use full absolute paths (e.g., `/Users/me/file.pdf`) |
 | No smart mailboxes | Cannot access Smart Mailboxes via AppleScript |
 | Very large mailboxes not searchable | Apple Mail's AppleScript bridge times out on mailboxes with tens of thousands of messages, so unscoped `search-messages` skips mailboxes above `APPLE_MAIL_MAX_SEARCH_MAILBOX` (default 5000) and reports them as a partial result. Scope with `mailbox` + a date window to search inside one. ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)) |
+| Can't delete/rename server-side mailboxes or mutate drafts | Mail.app's AppleScript bridge can only `delete`/`rename` **local "On My Mac"** mailboxes and cannot delete/move drafts — it throws `AppleEvent handler failed` for IMAP/Gmail/Workspace/iCloud/Exchange mailboxes and drafts (the GUI can do it). `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` now return a clear "do it in Mail.app directly" error in that case instead of a generic failure. ([#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) |
 | In-memory templates | Email templates are not persisted across server restarts |
 | Numeric-only message IDs | Message IDs must contain only digits (validated by schema) |
 | Batch size cap | Batch operations are limited to 100 messages per request |

package/build/index.js

@@ -25,6 +25,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { AppleMailManager } from "./services/appleMailManager.js";
 import { sendViaSmtp } from "./services/smtpMailer.js";
+import { isImapAccount, imapSearchMessages, imapListMessages } from "./services/imapClient.js";
 import { createSerialGate } from "./utils/serialize.js";
 // =============================================================================
 // Shared Validation Schemas
@@ -157,7 +158,23 @@ server.tool("search-messages", {
     dateFrom: DATE_FILTER_SCHEMA.describe("Start date filter (e.g., 'January 1, 2026')"),
     dateTo: DATE_FILTER_SCHEMA.describe("End date filter (e.g., 'March 1, 2026')"),
     limit: z.number().optional().describe("Maximum number of results (default: 50)"),
-}, withErrorHandling(({ query, mailbox, account, limit = 50, dateFrom, dateTo, from, subject, isRead, isFlagged, }) => {
+}, withErrorHandling(async ({ query, mailbox, account, limit = 50, dateFrom, dateTo, from, subject, isRead, isFlagged, }) => {
+    // IMAP backend (issue #43): server-side search when this account is
+    // explicitly configured for IMAP; otherwise fall through to AppleScript.
+    if (isImapAccount(account)) {
+        return successResponse(await imapSearchMessages({
+            query,
+            mailbox,
+            account,
+            limit,
+            dateFrom,
+            dateTo,
+            from,
+            subject,
+            isRead,
+            isFlagged,
+        }));
+    }
     const { messages, diagnostics } = mailManager.searchMessagesWithDiagnostics(query, mailbox, account, limit, dateFrom, dateTo, from, subject, isRead, isFlagged);
     const coverageBlock = partialCoverageBlock(diagnostics);
     if (messages.length === 0) {
@@ -200,7 +217,12 @@ server.tool("list-messages", {
     offset: z.number().optional().describe("Number of messages to skip (for pagination)"),
     from: z.string().optional().describe("Filter by sender email address or name"),
     unreadOnly: z.boolean().optional().describe("Only show unread messages"),
-}, withErrorHandling(({ mailbox, account, limit = 50, offset = 0, from }) => {
+}, withErrorHandling(async ({ mailbox, account, limit = 50, offset = 0, from, unreadOnly }) => {
+    // IMAP backend (issue #43): server-side listing when this account is
+    // explicitly configured for IMAP; otherwise fall through to AppleScript.
+    if (isImapAccount(account)) {
+        return successResponse(await imapListMessages({ mailbox, account, limit, offset, from, unreadOnly }));
+    }
     const { messages, diagnostics } = mailManager.listMessagesWithDiagnostics(mailbox, account, limit, from, offset);
     const coverageBlock = partialCoverageBlock(diagnostics);
     if (messages.length === 0) {
@@ -383,9 +405,9 @@ server.tool("unflag-message", {
 server.tool("delete-message", {
     id: MESSAGE_ID_SCHEMA,
 }, withErrorHandling(({ id }) => {
-    const success = mailManager.deleteMessage(id);
+    const { success, error } = mailManager.deleteMessage(id);
     if (!success) {
-        return errorResponse(`Failed to delete message "${id}"`);
+        return errorResponse(error || `Failed to delete message "${id}"`);
     }
     return successResponse("Message deleted");
 }, "Error deleting message"));
@@ -395,9 +417,9 @@ server.tool("move-message", {
     mailbox: z.string().min(1, "Destination mailbox is required"),
     account: z.string().optional().describe("Account containing the destination mailbox"),
 }, withErrorHandling(({ id, mailbox, account }) => {
-    const success = mailManager.moveMessage(id, mailbox, account);
+    const { success, error } = mailManager.moveMessage(id, mailbox, account);
     if (!success) {
-        return errorResponse(`Failed to move message to "${mailbox}"`);
+        return errorResponse(error || `Failed to move message to "${mailbox}"`);
     }
     return successResponse(`Message moved to "${mailbox}"`);
 }, "Error moving message"));
@@ -572,9 +594,9 @@ server.tool("delete-mailbox", {
     name: z.string().min(1, "Mailbox name is required"),
     account: z.string().optional().describe("Account containing the mailbox"),
 }, withErrorHandling(({ name, account }) => {
-    const success = mailManager.deleteMailbox(name, account);
+    const { success, error } = mailManager.deleteMailbox(name, account);
     if (!success) {
-        return errorResponse(`Failed to delete mailbox "${name}"`);
+        return errorResponse(error || `Failed to delete mailbox "${name}"`);
     }
     return successResponse(`Mailbox "${name}" deleted`);
 }, "Error deleting mailbox"));
@@ -584,9 +606,9 @@ server.tool("rename-mailbox", {
     newName: z.string().min(1, "New mailbox name is required"),
     account: z.string().optional().describe("Account containing the mailbox"),
 }, withErrorHandling(({ oldName, newName, account }) => {
-    const success = mailManager.renameMailbox(oldName, newName, account);
+    const { success, error } = mailManager.renameMailbox(oldName, newName, account);
     if (!success) {
-        return errorResponse(`Failed to rename mailbox "${oldName}" to "${newName}"`);
+        return errorResponse(error || `Failed to rename mailbox "${oldName}" to "${newName}"`);
     }
     return successResponse(`Mailbox renamed from "${oldName}" to "${newName}"`);
 }, "Error renaming mailbox"));

package/build/services/appleMailManager.d.ts

@@ -46,6 +46,14 @@ export declare function splitSearchDiagnostics(output: string, account: string):
  * (caller passes `resolve(...)` output).
  */
 export declare function isPathWithinAllowedRoots(resolvedPath: string): boolean;
+/**
+ * Turn a raw mailbox delete/rename failure into an actionable, non-retryable
+ * message when it's the known server-side-mailbox limitation (#42); otherwise
+ * return the raw error unchanged.
+ *
+ * Exported for unit testing.
+ */
+export declare function describeMailboxOpError(op: "delete" | "rename", raw: string): string;
 export declare function escapeForAppleScript(text: string): string;
 /**
  * Emits AppleScript that builds a date into the variable `varName` from numeric
@@ -328,7 +336,21 @@ export declare class AppleMailManager {
     /**
      * Delete a message.
      */
-    deleteMessage(id: string): boolean;
+    deleteMessage(id: string): {
+        success: boolean;
+        error?: string;
+    };
+    /**
+     * Classify a failed message mutation (delete/move) into an actionable error.
+     *
+     * Mail.app's scripting bridge cannot delete or move drafts, and cannot mutate
+     * messages in some server-side special mailboxes — it throws `AppleEvent
+     * handler failed` rather than a useful message (#42). When that pattern is
+     * seen, look up the message's mailbox (cheap, indexed `whose id is`) to give a
+     * draft-specific or server-specific hint. Other errors (e.g. "Message not
+     * found", "ambiguous destination") pass through unchanged.
+     */
+    private classifyMessageMutationError;
     /**
      * Move a message to a different mailbox.
      */
@@ -351,7 +373,10 @@ export declare class AppleMailManager {
      * (destination not found / ambiguous / message not found).
      */
     private moveMessageInternal;
-    moveMessage(id: string, mailbox: string, account?: string): boolean;
+    moveMessage(id: string, mailbox: string, account?: string): {
+        success: boolean;
+        error?: string;
+    };
     /**
      * Run one operation over many message IDs in a SINGLE osascript invocation.
      *
@@ -424,11 +449,17 @@ export declare class AppleMailManager {
     /**
      * Delete a mailbox.
      */
-    deleteMailbox(name: string, account?: string): boolean;
+    deleteMailbox(name: string, account?: string): {
+        success: boolean;
+        error?: string;
+    };
     /**
      * Rename a mailbox by creating a new one, moving messages, and deleting the old one.
      */
-    renameMailbox(oldName: string, newName: string, account?: string): boolean;
+    renameMailbox(oldName: string, newName: string, account?: string): {
+        success: boolean;
+        error?: string;
+    };
     /**
      * List all mail accounts (uses cache).
      */

package/build/services/appleMailManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appleMailManager.d.ts","sourceRoot":"","sources":["../../src/services/appleMailManager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"appleMailManager.d.ts","sourceRoot":"","sources":["../../src/services/appleMailManager.ts"],"names":[],"mappings":"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"}

package/build/services/appleMailManager.js

@@ -158,6 +158,29 @@ export function isPathWithinAllowedRoots(resolvedPath) {
         return resolvedPath === base || resolvedPath.startsWith(base + sep);
     });
 }
+/**
+ * Pattern in a raw AppleScript error that indicates an operation Mail.app's
+ * scripting interface simply cannot perform on this target — most often a
+ * server-side (IMAP / Gmail / Workspace / iCloud / Exchange) mailbox or a draft.
+ * Mail throws `AppleEvent handler failed` (-10000) for these; the GUI can do
+ * them, the scripting bridge cannot. See issue #42 and the audit doc.
+ */
+const UNSUPPORTED_APPLESCRIPT_OP = /AppleEvent handler failed|-10000/i;
+/**
+ * Turn a raw mailbox delete/rename failure into an actionable, non-retryable
+ * message when it's the known server-side-mailbox limitation (#42); otherwise
+ * return the raw error unchanged.
+ *
+ * Exported for unit testing.
+ */
+export function describeMailboxOpError(op, raw) {
+    const trimmed = (raw || "").trim();
+    if (UNSUPPORTED_APPLESCRIPT_OP.test(trimmed)) {
+        const verb = op === "delete" ? "Delete" : "Rename";
+        return `Mail.app cannot ${op} server-side (IMAP / Gmail / Workspace / iCloud / Exchange) mailboxes via AppleScript — only local "On My Mac" mailboxes support this. ${verb} it in Mail.app directly. (Mail.app error: ${trimmed})`;
+    }
+    return trimmed || `Failed to ${op} mailbox`;
+}
 export function escapeForAppleScript(text) {
     if (!text)
         return "";
@@ -1425,11 +1448,41 @@ export class AppleMailManager {
     deleteMessage(id) {
         const script = this.findMessageScript(id, "delete msg");
         const result = executeAppleScript(script, { timeoutMs: 60000 });
-        if (!result.success || result.output.startsWith("error:")) {
-            console.error(`Failed to delete message: ${result.error || result.output}`);
-            return false;
+        if (result.success && !result.output.startsWith("error:")) {
+            return { success: true };
         }
-        return true;
+        const raw = result.success
+            ? result.output.replace(/^error:/, "")
+            : result.error || "Unknown error";
+        const error = this.classifyMessageMutationError(id, raw, "delete");
+        console.error(`Failed to delete message: ${error}`);
+        return { success: false, error };
+    }
+    /**
+     * Classify a failed message mutation (delete/move) into an actionable error.
+     *
+     * Mail.app's scripting bridge cannot delete or move drafts, and cannot mutate
+     * messages in some server-side special mailboxes — it throws `AppleEvent
+     * handler failed` rather than a useful message (#42). When that pattern is
+     * seen, look up the message's mailbox (cheap, indexed `whose id is`) to give a
+     * draft-specific or server-specific hint. Other errors (e.g. "Message not
+     * found", "ambiguous destination") pass through unchanged.
+     */
+    classifyMessageMutationError(id, raw, op) {
+        const trimmed = (raw || "").trim();
+        if (!UNSUPPORTED_APPLESCRIPT_OP.test(trimmed))
+            return trimmed || `Failed to ${op} message`;
+        let mailbox = "";
+        try {
+            mailbox = this.getMessageById(id)?.mailbox ?? "";
+        }
+        catch {
+            /* best-effort; fall through to the generic server-side message */
+        }
+        if (/draft/i.test(mailbox)) {
+            return `Mail.app cannot ${op} drafts via AppleScript; ${op} it in Mail.app directly. (Mail.app error: ${trimmed})`;
+        }
+        return `Mail.app cannot ${op} this message via AppleScript (server-side or special mailbox${mailbox ? ` "${mailbox}"` : ""}); ${op} it in Mail.app directly. (Mail.app error: ${trimmed})`;
     }
     /**
      * Move a message to a different mailbox.
@@ -1501,11 +1554,12 @@ export class AppleMailManager {
         return { success: true };
     }
     moveMessage(id, mailbox, account) {
-        const { success, error } = this.moveMessageInternal(id, mailbox, account);
-        if (!success) {
-            console.error(`Failed to move message: ${error}`);
-        }
-        return success;
+        const res = this.moveMessageInternal(id, mailbox, account);
+        if (res.success)
+            return { success: true };
+        const error = this.classifyMessageMutationError(id, res.error || "Failed to move message", "move");
+        console.error(`Failed to move message: ${error}`);
+        return { success: false, error };
     }
     // ===========================================================================
     // Batch Operations
@@ -1938,11 +1992,15 @@ export class AppleMailManager {
     `);
         const result = executeAppleScript(script);
         if (!result.success || result.output.startsWith("error:")) {
-            console.error(`Failed to delete mailbox: ${result.error || result.output}`);
-            return false;
+            const raw = result.success
+                ? result.output.replace(/^error:/, "")
+                : result.error || "Unknown error";
+            const error = describeMailboxOpError("delete", raw);
+            console.error(`Failed to delete mailbox: ${error}`);
+            return { success: false, error };
         }
         this.invalidateCache();
-        return true;
+        return { success: true };
     }
     /**
      * Rename a mailbox by creating a new one, moving messages, and deleting the old one.
@@ -1951,7 +2009,10 @@ export class AppleMailManager {
         const targetAccount = this.resolveAccount(account);
         // Create the new mailbox
         if (!this.createMailbox(newName, targetAccount)) {
-            return false;
+            return {
+                success: false,
+                error: `Could not create the destination mailbox "${newName}" needed for the rename.`,
+            };
         }
         // Move all messages from old to new
         const resolvedOld = this.resolveMailbox(oldName, targetAccount);
@@ -1997,19 +2058,27 @@ export class AppleMailManager {
         // check), so a truncated move is recoverable rather than lossy.
         const result = executeAppleScript(moveScript, { timeoutMs: 120000 });
         if (!result.success || result.output.startsWith("error:")) {
-            console.error(`Failed to rename mailbox: ${result.error || result.output}`);
-            return false;
+            const raw = result.success
+                ? result.output.replace(/^error:/, "")
+                : result.error || "Unknown error";
+            // The empty destination mailbox we just created is now an orphan; the
+            // source is untouched (delete only runs after a verified-empty move).
+            const error = describeMailboxOpError("rename", raw);
+            console.error(`Failed to rename mailbox: ${error}`);
+            this.invalidateCache();
+            return { success: false, error };
         }
         if (result.output.startsWith("partial")) {
             const parts = result.output.split(FIELD_SEP);
             const remaining = parts[3] ?? "?";
             const total = parts[2] ?? "?";
-            console.error(`Failed to rename mailbox: only ${parts[1] ?? "?"} of ${total} messages moved, ${remaining} remain in "${resolvedOld}"; source was NOT deleted (both mailboxes left intact). Retry to move the rest.`);
+            const error = `Only ${parts[1] ?? "?"} of ${total} messages moved, ${remaining} remain in "${resolvedOld}"; the source was NOT deleted (both mailboxes left intact). Retry to move the rest.`;
+            console.error(`Failed to rename mailbox: ${error}`);
             this.invalidateCache(); // the new mailbox now exists and holds the moved messages
-            return false;
+            return { success: false, error };
         }
         this.invalidateCache();
-        return true;
+        return { success: true };
     }
     // ===========================================================================
     // Account Operations

package/build/services/imapClient.d.ts

@@ -0,0 +1,75 @@
+export declare const IMAP_ENV: {
+    readonly user: "APPLE_MAIL_MCP_IMAP_USER";
+    readonly account: "APPLE_MAIL_MCP_IMAP_ACCOUNT";
+    readonly host: "APPLE_MAIL_MCP_IMAP_HOST";
+    readonly port: "APPLE_MAIL_MCP_IMAP_PORT";
+    readonly password: "APPLE_MAIL_MCP_IMAP_PASSWORD";
+    readonly keychainService: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE";
+    readonly keychainAccount: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT";
+};
+export interface ImapConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+    accountLabel: string;
+}
+export interface ImapSearchArgs {
+    query?: string;
+    account?: string;
+    from?: string;
+    subject?: string;
+    mailbox?: string;
+    limit?: number;
+    dateFrom?: string;
+    dateTo?: string;
+    isRead?: boolean;
+    isFlagged?: boolean;
+    unreadOnly?: boolean;
+    offset?: number;
+}
+interface ImapAddress {
+    name?: string;
+    address?: string;
+}
+interface ImapEnvelope {
+    subject?: string;
+    date?: Date | string;
+    from?: ImapAddress[];
+}
+interface ImapMessage {
+    uid: number;
+    envelope?: ImapEnvelope;
+    flags?: Set<string>;
+}
+interface MailboxLock {
+    release: () => void;
+}
+export interface ImapClientLike {
+    connect(): Promise<void>;
+    getMailboxLock(path: string): Promise<MailboxLock>;
+    search(query: Record<string, unknown>, opts: {
+        uid: true;
+    }): Promise<number[] | false>;
+    fetch(range: string, query: Record<string, unknown>, opts: {
+        uid: true;
+    }): AsyncIterable<ImapMessage>;
+    logout(): Promise<void>;
+}
+export type ImapConnect = (cfg: ImapConfig) => Promise<ImapClientLike>;
+/** True only when IMAP is configured AND the explicit `account` matches it. */
+export declare function isImapAccount(account: string | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function resolveImapConfig(env?: NodeJS.ProcessEnv): ImapConfig;
+/** Map common (Gmail) mailbox names to their IMAP paths. */
+export declare function resolveMailboxPath(mailbox: string | undefined, mode: "search" | "list"): string;
+export declare function imapSearchMessages(args: ImapSearchArgs, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<string>;
+export declare function imapListMessages(args: ImapSearchArgs, deps?: {
+    connect?: ImapConnect;
+    config?: ImapConfig;
+}): Promise<string>;
+export {};
+//# sourceMappingURL=imapClient.d.ts.map

package/build/services/imapClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imapClient.d.ts","sourceRoot":"","sources":["../../src/services/imapClient.ts"],"names":[],"mappings":"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"}

package/build/services/imapClient.js

@@ -0,0 +1,177 @@
+/**
+ * IMAP backend for read/search (issue #43, Phase 1).
+ *
+ * AppleScript-over-Mail.app is the default. When an account is explicitly
+ * configured for IMAP (env below), `search-messages` and `list-messages` route
+ * here instead, running a SERVER-SIDE search — orders of magnitude faster than
+ * AppleScript's client-side `whose` enumeration on large Gmail mailboxes, and
+ * correct (no false-empty on timeout). Read-only; mutations stay on AppleScript.
+ *
+ * Opt-in via env (mirrors the SMTP transport pattern):
+ *   APPLE_MAIL_MCP_IMAP_USER      (required — enables IMAP; the login address)
+ *   APPLE_MAIL_MCP_IMAP_ACCOUNT   (Mail account name to match for routing; default = USER)
+ *   APPLE_MAIL_MCP_IMAP_HOST      (default imap.gmail.com)
+ *   APPLE_MAIL_MCP_IMAP_PORT      (default 993, implicit TLS)
+ *   APPLE_MAIL_MCP_IMAP_PASSWORD  (else Keychain via the two vars below)
+ *   APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE / _KEYCHAIN_ACCOUNT
+ *
+ * @module services/imapClient
+ */
+import { ImapFlow } from "imapflow";
+import { readKeychainPassword } from "../services/smtpMailer.js";
+export const IMAP_ENV = {
+    user: "APPLE_MAIL_MCP_IMAP_USER",
+    account: "APPLE_MAIL_MCP_IMAP_ACCOUNT",
+    host: "APPLE_MAIL_MCP_IMAP_HOST",
+    port: "APPLE_MAIL_MCP_IMAP_PORT",
+    password: "APPLE_MAIL_MCP_IMAP_PASSWORD",
+    keychainService: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE",
+    keychainAccount: "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT",
+};
+/** True only when IMAP is configured AND the explicit `account` matches it. */
+export function isImapAccount(account, env = process.env) {
+    const user = env[IMAP_ENV.user]?.trim();
+    if (!user || !account)
+        return false;
+    const label = env[IMAP_ENV.account]?.trim() || user;
+    return account === label || account === user;
+}
+export function resolveImapConfig(env = process.env) {
+    const user = env[IMAP_ENV.user]?.trim();
+    if (!user) {
+        throw new Error(`IMAP not configured. Set ${IMAP_ENV.user} (login address) to enable it.`);
+    }
+    const host = env[IMAP_ENV.host]?.trim() || "imap.gmail.com";
+    const port = env[IMAP_ENV.port] ? Number.parseInt(env[IMAP_ENV.port], 10) : 993;
+    if (!Number.isInteger(port) || port <= 0) {
+        throw new Error(`Invalid ${IMAP_ENV.port}: "${env[IMAP_ENV.port]}".`);
+    }
+    let pass = env[IMAP_ENV.password];
+    if (!pass) {
+        const svc = env[IMAP_ENV.keychainService]?.trim();
+        const acct = env[IMAP_ENV.keychainAccount]?.trim() || user;
+        if (svc)
+            pass = readKeychainPassword(svc, acct) ?? undefined;
+    }
+    if (!pass) {
+        throw new Error(`No IMAP password. Set ${IMAP_ENV.password}, or ${IMAP_ENV.keychainService}/${IMAP_ENV.keychainAccount} for the Keychain.`);
+    }
+    return {
+        host,
+        port,
+        secure: port === 993,
+        user,
+        pass,
+        accountLabel: env[IMAP_ENV.account]?.trim() || user,
+    };
+}
+const defaultConnect = async (cfg) => {
+    const client = new ImapFlow({
+        host: cfg.host,
+        port: cfg.port,
+        secure: cfg.secure,
+        auth: { user: cfg.user, pass: cfg.pass },
+        logger: false,
+    });
+    await client.connect();
+    return client;
+};
+/** Map common (Gmail) mailbox names to their IMAP paths. */
+export function resolveMailboxPath(mailbox, mode) {
+    if (!mailbox)
+        return mode === "search" ? "[Gmail]/All Mail" : "INBOX";
+    const map = {
+        "all mail": "[Gmail]/All Mail",
+        "sent mail": "[Gmail]/Sent Mail",
+        sent: "[Gmail]/Sent Mail",
+        trash: "[Gmail]/Trash",
+        drafts: "[Gmail]/Drafts",
+        spam: "[Gmail]/Spam",
+        junk: "[Gmail]/Spam",
+        starred: "[Gmail]/Starred",
+        important: "[Gmail]/Important",
+    };
+    return map[mailbox.trim().toLowerCase()] ?? mailbox;
+}
+function buildCriteria(a, listMode) {
+    const c = {};
+    if (a.query)
+        c.or = [{ subject: a.query }, { from: a.query }];
+    if (a.from)
+        c.from = a.from;
+    if (a.subject)
+        c.subject = a.subject;
+    if (a.isRead === true)
+        c.seen = true;
+    if (a.isRead === false)
+        c.unseen = true;
+    if (a.unreadOnly && listMode)
+        c.unseen = true;
+    if (a.isFlagged === true)
+        c.flagged = true;
+    if (a.isFlagged === false)
+        c.unflagged = true;
+    if (a.dateFrom)
+        c.since = new Date(a.dateFrom);
+    if (a.dateTo)
+        c.before = new Date(a.dateTo);
+    if (Object.keys(c).length === 0)
+        c.all = true;
+    return c;
+}
+function formatRow(m) {
+    const env = m.envelope ?? {};
+    const subject = env.subject || "(no subject)";
+    const a = env.from?.[0];
+    const from = a
+        ? a.name
+            ? `${a.name} <${a.address ?? ""}>`
+            : (a.address ?? "(unknown)")
+        : "(unknown)";
+    const date = env.date ? new Date(env.date).toLocaleDateString() : "";
+    const read = m.flags?.has("\\Seen") ? "read" : "unread";
+    return `  - UID: ${m.uid} | ${date} | ${subject} (from: ${from}) [${read}]`;
+}
+async function run(args, listMode, deps) {
+    const cfg = deps.config ?? resolveImapConfig();
+    const client = await (deps.connect ?? defaultConnect)(cfg);
+    try {
+        const path = resolveMailboxPath(args.mailbox, listMode ? "list" : "search");
+        const lock = await client.getMailboxLock(path);
+        try {
+            const found = await client.search(buildCriteria(args, listMode), { uid: true });
+            const uids = Array.isArray(found) ? found : [];
+            if (uids.length === 0) {
+                return `No messages found via IMAP in "${path}" (account ${cfg.accountLabel}).`;
+            }
+            const limit = args.limit ?? 50;
+            const offset = args.offset ?? 0;
+            // UIDs are ascending → newest are the highest. Apply offset+limit from the newest end.
+            const newest = uids
+                .slice()
+                .reverse()
+                .slice(offset, offset + limit);
+            const byUid = new Map();
+            for await (const msg of client.fetch(newest.join(","), { envelope: true, flags: true }, { uid: true })) {
+                byUid.set(msg.uid, formatRow(msg));
+            }
+            const rows = newest.map((u) => byUid.get(u)).filter((r) => Boolean(r));
+            const verb = listMode ? "listed" : "matched";
+            return (`Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, mailbox "${path}"; ${uids.length} total ${verb}):\n` +
+                rows.join("\n") +
+                `\n\nNote: IDs are IMAP UIDs. get-message and message mutations still use the AppleScript path (Phase 1 is read/search only).`);
+        }
+        finally {
+            lock.release();
+        }
+    }
+    finally {
+        await client.logout().catch(() => undefined);
+    }
+}
+export function imapSearchMessages(args, deps = {}) {
+    return run(args, false, deps);
+}
+export function imapListMessages(args, deps = {}) {
+    return run(args, true, deps);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "1.6.9",
+  "version": "1.7.0",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude",
   "type": "module",
   "main": "build/index.js",
@@ -59,6 +59,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "imapflow": "^1.4.1",
     "nodemailer": "^9.0.0",
     "zod": "^3.22.4"
   },