apple-mail-mcp 2.8.3 → 2.8.4

package/README.md

@@ -98,6 +98,25 @@ npm install -g github:sweetrb/apple-mail-mcp
 
 On first use, macOS will ask for permission to automate Mail.app. Click "OK" to allow.
 
+## Configuring email (IMAP & SMTP)
+
+The server works out of the box over AppleScript with **no configuration**. Two
+**opt-in** power features take a one-time setup:
+
+- **Fast IMAP reads** — server-side search, counts, and large-mailbox handling
+  that AppleScript is too slow for (it times out on big Gmail mailboxes).
+- **Clean SMTP sending** — `send-email` submits clean MIME directly, avoiding the
+  macOS 15+ Mail.app `<blockquote>` wrapping that otherwise makes sent mail look
+  quoted/indented like a reply.
+
+Both are driven by non-secret `APPLE_MAIL_MCP_*` settings — supplied via an `env`
+block **or** a `config.json` file (for hosts like Claude Desktop that strip `env`)
+— with passwords kept in the macOS **Keychain**, never in config.
+
+👉 **[IMAP / SMTP Setup Guide](docs/IMAP-SETUP.md)** — step-by-step: app passwords,
+Keychain, both config methods, multi-account, SMTP, verification with the `doctor`
+tool, and troubleshooting. Verify any time by running the **`doctor`** tool.
+
 ## Requirements
 
 - **macOS** - Apple Mail and AppleScript are macOS-only

package/build/index.js

@@ -80733,6 +80733,8 @@ async function routeMessage(id, opts) {
 }
 
 // src/tools/doctor.ts
+var SETUP_GUIDE = "https://github.com/sweetrb/apple-mail-mcp/blob/main/docs/IMAP-SETUP.md";
+var CONFIG_FILE_HINT = "If your MCP host ignores the server 'env' block (e.g. Claude Desktop), put these in ~/Library/Application Support/apple-mail-mcp/config.json instead";
 async function runDoctor(mailManager2) {
   const checks = [];
   const hc = mailManager2.healthCheck();
@@ -80764,7 +80766,7 @@ async function runDoctor(mailManager2) {
     checks.push({
       name: "IMAP backend",
       status: "warn",
-      detail: `not configured \u2014 AppleScript is used for all accounts. Set ${IMAP_ENV.user} (+ Keychain/password), or ${IMAP_ENV.accounts} for multiple accounts, to enable server-side search and server-mailbox ops.`
+      detail: `not configured \u2014 AppleScript is used for all accounts. Set ${IMAP_ENV.user} (+ Keychain/password), or ${IMAP_ENV.accounts} for multiple accounts, to enable server-side search and server-mailbox ops. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
     });
   } else {
     for (const label of imapAccounts) {
@@ -80780,7 +80782,7 @@ async function runDoctor(mailManager2) {
   checks.push({
     name: "SMTP transport",
     status: isSmtpConfigured() ? "ok" : "warn",
-    detail: isSmtpConfigured() ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.` : `not configured \u2014 send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable.`
+    detail: isSmtpConfigured() ? `configured (${smtpHost}); send-email auto-prefers clean SMTP (no Mail.app Sent-folder copy; a non-email "account" label still routes to AppleScript). Pass transport:"applescript" to force Mail.app. The apple-mail-send CLI is also available.` : `not configured \u2014 send-email uses AppleScript (subject to macOS 15+ blockquote wrapping). Set ${SMTP_ENV.host} and ${SMTP_ENV.user} (+ password via Keychain) to enable. ${CONFIG_FILE_HINT}. Setup guide: ${SETUP_GUIDE}`
   });
   const healthy = !checks.some((c) => c.status === "fail");
   return { healthy, checks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.8.3",
+  "version": "2.8.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",