apple-mail-mcp 2.10.2 → 2.10.4

package/README.md

@@ -147,6 +147,7 @@ tool, and troubleshooting. Verify any time by running the **`doctor`** tool.
 
 - **macOS** - Apple Mail and AppleScript are macOS-only
 - **Node.js 20+** - Required for the MCP server
+- **Node.js 22.5+ and Full Disk Access** - Required by `search-contacts` only. It reads the Contacts database directly through Node's built-in `node:sqlite`, which does not exist before 22.5. On an older runtime, or without Full Disk Access for the Node binary, it logs one line to stderr and returns **an empty list rather than an error** — so "no contacts found" can mean "cannot read Contacts". Every other tool works on Node 20+. See [Node runtime & TCC permissions](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
 - **Apple Mail** - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)
 
 ## Features
@@ -264,6 +265,8 @@ Get the full content of a message.
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
 | `preferHtml` | boolean | No | Return HTML source instead of plain text |
+| `mailbox` | string | No | Mailbox holding the message (e.g. `"Sent Items"`). With `account`, opens that mailbox directly instead of scanning every mailbox — this is the fix for timeouts on large folders |
+| `account` | string | No | Account holding the message. Pair with `mailbox` to skip the cross-mailbox scan |
 
 **Returns:** Subject line and message body (plain text by default, HTML if `preferHtml` is true and HTML content is available).
 
@@ -668,7 +671,7 @@ Return an attachment's bytes as base64 (the read counterpart to inline-base64 se
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `id` | string | Yes | Numeric message ID |
+| `id` | string | Yes | Message ID (numeric or `imap:…`) |
 | `attachmentName` | string | Yes | Attachment filename (from `list-attachments`) |
 
 **Returns:** The attachment bytes, base64-encoded (also in `structuredContent.contentBase64`).
@@ -748,6 +751,8 @@ Flag or unflag a message. `flag-message` optionally takes a flag **color**; `unf
 
 **Flag colors** are an Apple Mail feature — the message's `flag index` (0 red, 1 orange, 2 yellow, 3 green, 4 blue, 5 purple, 6 gray), which is the property a Mail smart mailbox can match on. **The color is applied on both routes** (since 2.10.0): AppleScript sets the flag index directly, and for an **IMAP-routed** id (`imap:…`) the color is written as Mail.app's `$MailFlagBit0/1/2` keywords — a 3-bit field holding the same palette index. `\Flagged` on its own really is colorless, but those keywords ride alongside it in an ordinary `UID STORE`, so a smart mailbox keyed on flag color matches an IMAP-flagged message too. You do **not** need to resolve to a numeric id just to color a flag.
 
+To **read** a color, the IMAP read path returns `flagColorIndex` in `structuredContent` — the same 0-6 palette index, omitted when the message carries no color bits. The AppleScript read path does not populate it.
+
 ---
 
 #### `delete-message`
@@ -853,8 +858,12 @@ Get unread message count.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `mailbox` | string | No | Mailbox to check (omit for total) |
-| `account` | string | No | Account to check |
+| `mailbox` | string | No | Mailbox to check (omit for **INBOX**) |
+| `account` | string | No | Account to check (omit to sum each account's INBOX) |
+
+**Returns:** The unread count for the requested scope.
+
+> Omitting `mailbox` counts **INBOX**, not a cross-mailbox total. This changed in 2.8.15: summing every mailbox was slow and wrong on Gmail, where one message appears in INBOX, All Mail and every label it carries. For account-wide totals use [`get-mail-stats`](#get-mail-stats).
 
 ---
 
@@ -896,6 +905,8 @@ Rename a mailbox (creates new, moves messages, deletes old).
 
 ### Smart Mailbox Operations (intelligente Postfächer)
 
+> **Requires Full Disk Access.** These tools read and write `~/Library/Mail/V*/MailData/SyncedSmartMailboxes.plist`, which is TCC-protected. Without Full Disk Access for the server's Node runtime the read simply finds nothing, and the tools report "no smart mailboxes" or "launch Mail at least once" rather than a permission error — see [Node runtime & TCC permissions](https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md).
+
 Smart mailboxes are Apple Mail's **criteria-based virtual views** — not real folders, so no messages are moved. AppleScript's `smart mailbox` / `intelligentes Postfach` terms don't compile reliably on localized (e.g. German) macOS, so these tools read and edit `~/Library/Mail/V*/MailData/SyncedSmartMailboxes.plist` directly.
 
 **How writes stay safe:** creating or deleting a smart mailbox first backs the plist up to `SyncedSmartMailboxes.plist.bak`, edits a temp copy with `plutil`/`PlistBuddy`, validates it with `plutil -lint`, and only then atomically renames it into place. Your **existing** smart mailboxes — including any with date/data criteria — are never rewritten, only the single target entry is added or removed. These tools do **not** quit or restart Mail: **quit Mail first** for reliable results, since a running Mail may not show a new smart mailbox until it's relaunched and can overwrite plist edits it didn't make.
@@ -1030,14 +1041,15 @@ Delete a mail rule by name.
 
 #### `search-contacts`
 
-Search contacts in Contacts.app.
+Search the macOS Contacts database by name, organization, nickname, or email substring.
+
+Since 2.8.7 this reads the AddressBook SQLite files directly rather than driving Contacts.app over AppleScript, so **Contacts.app need not be running and no Automation grant is involved** — but the Node runtime does need **Full Disk Access**, and **Node 22.5+** (see [Requirements](#requirements)). Without either, the tool returns an empty list rather than an error.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `query` | string | Yes | Name to search for |
-| `limit` | number | No | Max results (default: 10) |
+| `query` | string | Yes | Substring matched against full name, organization, nickname, or any email address |
 
-**Returns:** List of contacts with name, email addresses, and phone numbers.
+**Returns:** List of contacts with name, email addresses, and phone numbers. Results are **not** truncated — a broad query returns every match.
 
 ---
 
@@ -1130,7 +1142,9 @@ Run a full setup diagnostic: Mail.app automation permission, account state (flag
 
 Get mail statistics.
 
-**Parameters:** None
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `account` | string | No | Limit to one account (uses fast IMAP `STATUS` when that account is IMAP-configured). Omit to merge across all accounts. |
 
 **Returns:** Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d).
 
@@ -1271,7 +1285,7 @@ The entrypoint is written as:
 
 ## Security and Privacy
 
-- **Local only** - All operations happen locally via AppleScript. No data is sent to external servers.
+- **No third parties** - The server talks only to Mail.app on this Mac (AppleScript) and, when you configure them, directly to **your own** mail provider over TLS (IMAP/SMTP). Nothing is sent to this project or any other service. With the default AppleScript backend everything stays on-device; the opt-in IMAP/SMTP backends necessarily reach your provider, which is what they are for.
 - **Permission required** - macOS will prompt for automation permission on first use.
 - **No credential storage** - The server doesn't store any passwords or authentication tokens.
 - **Email safety** - Use `create-draft` to review emails before sending.
@@ -1285,7 +1299,7 @@ The entrypoint is written as:
 | macOS only | Apple Mail and AppleScript are macOS-specific |
 | MCP `send-email` is plain-text | The `send-email` tool sends plain text (reading HTML content is supported). To send HTML, use the bundled `apple-mail-send` CLI with `--html-body-file` (sends `multipart/alternative` via SMTP) |
 | 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 |
+| Smart mailboxes need Mail quit | Smart mailboxes are supported (see [Smart Mailbox Operations](#smart-mailbox-operations-intelligente-postfächer)), but `create-`/`delete-smart-mailbox` edit `SyncedSmartMailboxes.plist` directly — a running Mail may not show a new one until relaunched, and can overwrite plist edits it didn't make. Quit Mail first. Reading them needs Full Disk Access for the Node runtime |
 | Very large mailboxes not searchable *via AppleScript* | 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 — or configure the [IMAP backend](#imap-backend--opt-in), which searches these server-side in well under a second. ([#24](https://github.com/sweetrb/apple-mail-mcp/issues/24)) |
 | Can't delete/rename server-side mailboxes or mutate drafts *via AppleScript* | 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 (the GUI can do it). Without IMAP configured, `delete-mailbox`/`rename-mailbox`/`delete-message`/`move-message` return a clear "do it in Mail.app directly" error instead of a generic failure. With the [IMAP backend](#imap-backend--opt-in) configured for the account, these operations run via IMAP and succeed. ([#42](https://github.com/sweetrb/apple-mail-mcp/issues/42)) |
 | Message ID format | Message IDs must be numeric (AppleScript ids) or `imap:…` tokens from the IMAP read path (validated by schema) |
@@ -1385,14 +1399,16 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ## Development
 
+This repo is **pnpm-only** — `package.json`'s `preinstall` guard hard-fails an `npm install`, because npm resolves off-lockfile and the committed bundle would then mismatch CI.
+
 ```bash
-npm install            # Install dependencies
-npm run build          # Typecheck, then bundle src/index.ts + src/cli.ts into build/ (esbuild)
-npm test               # Run unit tests
-npm run test:integration  # Run integration tests (requires Mail.app)
-npm run test:all       # Run all tests (unit + integration)
-npm run lint           # Check code style
-npm run format         # Format code
+corepack enable && pnpm install --frozen-lockfile   # Install dependencies
+pnpm run build             # Typecheck, then bundle src/index.ts + src/cli.ts into build/ (esbuild)
+pnpm test                  # Run unit tests
+pnpm run test:integration  # Run integration tests (requires Mail.app)
+pnpm run test:all          # Run all tests (unit + integration)
+pnpm run lint              # Check code style
+pnpm run format            # Format code
 ```
 
 ---

package/build/index.js

@@ -76079,6 +76079,10 @@ function executeAppleScript(script, options = {}) {
   return lastError;
 }
 
+// src/utils/docsUrls.ts
+var SETUP_GUIDE_URL = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
+var SETUP_HINT = `Setup guide: ${SETUP_GUIDE_URL} \u2014 run the "doctor" tool to check your setup.`;
+
 // src/utils/mimeParse.ts
 function extractBoundary(source) {
   const match = source.match(/boundary="?([^";\s\r\n]+)"?/i);
@@ -76838,6 +76842,12 @@ var AppleMailManager = class {
   };
   /** Cache TTL in milliseconds (60 seconds). */
   CACHE_TTL_MS = 6e4;
+  /**
+   * Last AppleScript transport error from an account/count read, or null when the
+   * last one succeeded. Lets a tool report "the transport failed" instead of
+   * presenting a fallback zero/empty as a real answer. (#130)
+   */
+  lastAccountsError = null;
   /**
    * Remembers where each message id was last seen: id → {account, mailbox}.
    *
@@ -76873,6 +76883,10 @@ var AppleMailManager = class {
       return this.cache.accounts.data;
     }
     const accounts = this.fetchAccounts();
+    if (accounts === null) {
+      return this.cache.accounts?.data ?? [];
+    }
+    this.lastAccountsError = null;
     this.cache.accounts = { data: accounts, expiry: now + this.CACHE_TTL_MS };
     return accounts;
   }
@@ -76974,7 +76988,7 @@ var AppleMailManager = class {
   serverSideCreateGuard(account, op) {
     if (this.isServerSideAccount(account) === true) {
       const verb = op === "rename" ? "rename" : "create";
-      return `Account "${account}" stores its mailboxes on the server (IMAP / iCloud / Exchange), and Mail.app cannot ${verb} server-side mailboxes via AppleScript \u2014 a ${verb} would ${op === "rename" ? "leave a half-created orphan" : "orphan a mailbox that can never be removed"}. Configure IMAP for this account (APPLE_MAIL_MCP_IMAP_*) so mailbox create/delete/rename route through the server, or manage the folder in Mail.app directly.`;
+      return `Account "${account}" stores its mailboxes on the server (IMAP / iCloud / Exchange), and Mail.app cannot ${verb} server-side mailboxes via AppleScript \u2014 a ${verb} would ${op === "rename" ? "leave a half-created orphan" : "orphan a mailbox that can never be removed"}. Configure IMAP for this account (APPLE_MAIL_MCP_IMAP_*) so mailbox create/delete/rename route through the server, or manage the folder in Mail.app directly. ${SETUP_HINT}`;
     }
     return null;
   }
@@ -78679,6 +78693,7 @@ var AppleMailManager = class {
     const result = executeAppleScript(script, { timeoutMs: 6e4 });
     if (!result.success) {
       console.error(`Failed to get unread count: ${result.error}`);
+      this.lastAccountsError = result.error ?? "AppleScript transport failed";
       return 0;
     }
     return parseInt(result.output) || 0;
@@ -79204,9 +79219,38 @@ end tell`;
   listAccounts() {
     return this.getCachedAccounts();
   }
+  /**
+   * listAccounts() plus whether the underlying AppleScript read actually worked.
+   *
+   * `failed: true` means the list is a fallback (stale cache or empty) because the
+   * transport errored — NOT that Mail has no accounts. (#130)
+   */
+  listAccountsChecked() {
+    this.lastAccountsError = null;
+    const accounts = this.getCachedAccounts();
+    const error2 = this.lastAccountsError;
+    return error2 ? { accounts, failed: true, error: error2 } : { accounts, failed: false };
+  }
+  /**
+   * getUnreadCount() plus whether the AppleScript read actually worked.
+   *
+   * On failure the count is `null` rather than 0, so a caller can never mistake a
+   * wedged transport for an empty inbox. (#130)
+   */
+  getUnreadCountChecked(mailbox, account) {
+    this.lastAccountsError = null;
+    const count = this.getUnreadCount(mailbox, account);
+    const error2 = this.lastAccountsError;
+    return error2 ? { count: null, failed: true, error: error2 } : { count, failed: false };
+  }
   /**
    * Fetches account list directly from Mail.app via AppleScript.
    * Used internally by the cache; prefer getCachedAccounts() or listAccounts().
+   *
+   * Returns `null` when the AppleScript transport itself failed (timeout, wedged
+   * Mail, denied Automation). That is deliberately distinct from `[]`, which means
+   * "Mail answered, and there genuinely are no accounts" — collapsing the two is
+   * what let a wedged transport report a confident "No Mail accounts found". (#130)
    */
   fetchAccounts() {
     const script = buildAppLevelScript(`
@@ -79227,7 +79271,8 @@ end tell`;
     const result = executeAppleScript(script);
     if (!result.success) {
       console.error(`Failed to list accounts: ${result.error}`);
-      return [];
+      this.lastAccountsError = result.error ?? "AppleScript transport failed";
+      return null;
     }
     if (!result.output.trim()) return [];
     const items = result.output.split(RECORD_SEP);
@@ -79739,12 +79784,6 @@ var import_nodemailer = __toESM(require_nodemailer(), 1);
 import { execFileSync } from "child_process";
 import { isAbsolute as isAbsolute2 } from "path";
 import { existsSync as existsSync4 } from "fs";
-
-// src/utils/docsUrls.ts
-var SETUP_GUIDE_URL = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
-var SETUP_HINT = `Setup guide: ${SETUP_GUIDE_URL} \u2014 run the "doctor" tool to check your setup.`;
-
-// src/services/smtpMailer.ts
 var SMTP_ENV = {
   host: "APPLE_MAIL_MCP_SMTP_HOST",
   port: "APPLE_MAIL_MCP_SMTP_PORT",
@@ -80144,7 +80183,7 @@ function specToConfig(spec) {
   }
   if (!pass) {
     throw new Error(
-      `No IMAP password for account "${spec.accountLabel}". Set a password or a Keychain service/account.`
+      `No IMAP password for account "${spec.accountLabel}". Set a password or a Keychain service/account. ${SETUP_HINT}`
     );
   }
   return {
@@ -82826,7 +82865,7 @@ ${mailboxList}`, structured);
 server.registerTool(
   "get-unread-count",
   {
-    description: "Use when: you only need the number of unread messages \u2014 INBOX by default, or scoped to one mailbox and/or account \u2014 without listing the messages themselves.\nReturns: the unread count for the requested scope (INBOX when no mailbox is given).\nDo not use when: you need the actual unread messages and their ids (use list-messages with unreadOnly, or search-messages with isRead=false) or broader totals across every mailbox (use get-mail-stats).",
+    description: "Use when: you only need the number of unread messages \u2014 INBOX by default, or scoped to one mailbox and/or account \u2014 without listing the messages themselves.\nReturns: the unread count for the requested scope (INBOX when no mailbox is given). If a source cannot be read the result carries `partial: true` + `failedAccounts`, and a total AppleScript failure returns an ERROR \u2014 a plain count is never a disguised transport failure.\nDo not use when: you need the actual unread messages and their ids (use list-messages with unreadOnly, or search-messages with isRead=false) or broader totals across every mailbox (use get-mail-stats).",
     inputSchema: {
       mailbox: external_exports.string().optional().describe("Mailbox to check (default: INBOX)"),
       account: external_exports.string().optional().describe("Account to check")
@@ -82834,11 +82873,14 @@ server.registerTool(
     outputSchema: {
       unread: external_exports.number().optional(),
       mailbox: external_exports.string().optional(),
-      account: external_exports.string().optional()
+      account: external_exports.string().optional(),
+      partial: external_exports.boolean().optional(),
+      failedAccounts: external_exports.array(external_exports.string()).optional()
     }
   },
   withErrorHandling(async ({ mailbox, account }) => {
     let count;
+    const failedAccounts = [];
     if (shouldUseImap(account)) {
       if (account !== void 0) {
         count = await imapUnreadCount(mailbox, { account });
@@ -82851,17 +82893,32 @@ server.registerTool(
               total += await imapUnreadCount(mailbox, { config: src.config });
             } catch (e) {
               console.error(`IMAP unread-count failed for "${src.label}": ${String(e)}`);
+              failedAccounts.push(src.label);
             }
           } else {
-            total += mailManager.getUnreadCount(mailbox, src.account.name);
+            const r = mailManager.getUnreadCountChecked(mailbox, src.account.name);
+            if (r.failed) failedAccounts.push(src.account.name);
+            else total += r.count ?? 0;
           }
         }
         count = total;
       }
     } else {
-      count = mailManager.getUnreadCount(mailbox, account);
+      const r = mailManager.getUnreadCountChecked(mailbox, account);
+      if (r.failed) {
+        return errorResponse(
+          `Could not read the unread count \u2014 the AppleScript transport failed: ${r.error}. This is NOT the same as zero unread. Mail may be busy, wedged, or missing an Automation grant; run the "doctor" tool to check.`
+        );
+      }
+      count = r.count ?? 0;
     }
     const location = mailbox ? ` in "${mailbox}"` : "";
+    if (failedAccounts.length > 0) {
+      return successResponse(
+        `${count} unread message(s)${location} \u2014 PARTIAL: ${failedAccounts.length} account(s) could not be read (${failedAccounts.join(", ")}), so the real total is higher. Run the "doctor" tool to check.`,
+        { unread: count, mailbox, account, partial: true, failedAccounts }
+      );
+    }
     return successResponse(`${count} unread message(s)${location}`, {
       unread: count,
       mailbox,
@@ -83091,16 +83148,23 @@ ${lines || "  (none met the threshold)"}`,
 server.registerTool(
   "list-accounts",
   {
-    description: "Use when: discovering the configured Mail accounts (e.g. iCloud, Gmail) so you can pass an exact account name to other tools.\nReturns: the account names and a count.\nDo not use when: you want the folders within an account (use list-mailboxes) or messages (use list-messages / search-messages).",
+    description: "Use when: discovering the configured Mail accounts (e.g. iCloud, Gmail) so you can pass an exact account name to other tools.\nReturns: the account names and a count. If the AppleScript transport fails (timeout / wedged Mail / missing Automation grant) this returns an ERROR rather than an empty list \u2014 an empty list always means Mail really has no accounts.\nDo not use when: you want the folders within an account (use list-mailboxes) or messages (use list-messages / search-messages).",
     inputSchema: {},
     outputSchema: {
       accounts: external_exports.array(external_exports.object({}).passthrough()).optional(),
-      count: external_exports.number().optional()
+      count: external_exports.number().optional(),
+      partial: external_exports.boolean().optional(),
+      error: external_exports.string().optional()
     }
   },
   withErrorHandling(() => {
-    const accounts = mailManager.listAccounts();
-    const structured = { accounts, count: accounts.length };
+    const { accounts, failed, error: error2 } = mailManager.listAccountsChecked();
+    const structured = failed ? { accounts, count: accounts.length, partial: true, error: error2 } : { accounts, count: accounts.length };
+    if (failed) {
+      return errorResponse(
+        `Could not read the Mail account list \u2014 the AppleScript transport failed: ${error2}. This is NOT the same as having no accounts. Mail may be busy, wedged, or missing an Automation grant; run the "doctor" tool to check.`
+      );
+    }
     if (accounts.length === 0) {
       return successResponse("No Mail accounts found", structured);
     }
@@ -83252,7 +83316,7 @@ server.registerTool(
   withErrorHandling(({ query }) => {
     const contacts = mailManager.searchContacts(query);
     const structured = {
-      contacts: contacts.map((c) => ({ name: c.name, emails: c.emails })),
+      contacts: contacts.map((c) => ({ name: c.name, emails: c.emails, phones: c.phones })),
       count: contacts.length
     };
     if (contacts.length === 0) {
@@ -83260,7 +83324,8 @@ server.registerTool(
     }
     const contactList = contacts.map((c) => {
       const emails = c.emails.length > 0 ? c.emails.join(", ") : "no email";
-      return `  - ${c.name} (${emails})`;
+      const phones = c.phones.length > 0 ? `; ${c.phones.join(", ")}` : "";
+      return `  - ${c.name} (${emails}${phones})`;
     }).join("\n");
     return successResponse(`Found ${contacts.length} contact(s):
 ${contactList}`, structured);

package/docs/IMAP-SETUP.md

@@ -160,9 +160,22 @@ non-secret config goes here — passwords stay in the Keychain.**
 ### `APPLE_MAIL_MCP_IMAP_ACCOUNT` and routing
 
 `APPLE_MAIL_MCP_IMAP_ACCOUNT` should equal the **Mail.app account name** (what
-`list-accounts` shows). A tool call routes to IMAP only when its `account`
-argument matches a configured account's name or login — so this value is how the
-server knows "calls for this account go to IMAP."
+`list-accounts` shows), because that is how an **explicitly named** `account`
+argument is matched to an IMAP config.
+
+**Since v2.6.0 you do not need to pass `account` at all for reads.** When any
+IMAP account is configured, the read tools (`search-messages`, `get-thread`,
+`list-messages`, `list-mailboxes`, `get-unread-count`, `get-mail-stats`) prefer
+IMAP automatically:
+
+- explicit IMAP `account` → that account over IMAP;
+- explicit non-IMAP `account` → AppleScript;
+- **no `account` → fan out over every configured IMAP account**, with AppleScript
+  used only for the accounts no IMAP config covers.
+
+The name still matters for targeting a specific account and for the
+mailbox-write ops (`create`/`delete`/`rename-mailbox`), which route to IMAP only
+for an explicitly named IMAP account.
 
 ### Multiple accounts
 
@@ -285,9 +298,17 @@ and a server started there can't read passwords either. Options:
   restrict the config file's permissions to the service account.
 
 **Calls aren't routing to IMAP even though `doctor` shows connected.**
-The tool's `account` argument must match the configured account's name/login.
-Set `APPLE_MAIL_MCP_IMAP_ACCOUNT` to the exact Mail.app account name from
-`list-accounts`, and pass that same `account` to tools.
+For the six **read** tools this should not happen since v2.6.0 — they prefer IMAP
+as soon as any account is configured, with no `account` argument needed. If reads
+still look like AppleScript (slow, or partial-coverage warnings), the usual cause
+is that the server never saw your settings at all: a host that strips the `env`
+block (use the `config.json` method), or a Keychain service/account mismatch so
+the password lookup fails. Run `doctor` — it reports each account separately.
+
+For **targeting one specific account**, and for the mailbox-write ops
+(`create`/`delete`/`rename-mailbox`), the `account` argument must match the
+configured account's name/login: set `APPLE_MAIL_MCP_IMAP_ACCOUNT` to the exact
+Mail.app account name from `list-accounts` and pass that same `account`.
 
 **A disabled Mail account.** IMAP connects to the server directly, so it works
 even if the account is disabled in Mail.app — useful for reaching an account the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.10.2",
+  "version": "2.10.4",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",