Apple Mail MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to read, send, search, and manage emails in Apple Mail on macOS.

Note: This is the npm/Node.js package — install with npx or npm. There is an unrelated Python project of the same name on PyPI (imdinu/apple-mail-mcp) installed via pipx/uvx. If you're using uvx and seeing a cyclopts dependency error, you're looking for that project, not this one.

What is This?

This server acts as a bridge between AI assistants and Apple Mail. Once configured, you can ask Claude (or any MCP-compatible AI) to:

• "Check my inbox for unread messages"

• "Find emails from john@example.com"

• "Send an email to the team about the meeting"

• "Create a draft email for me to review"

• "Reply to that message"

• "Forward this to my colleague"

• "Move old newsletters to the Archive folder"

The AI assistant communicates with this server, which then uses AppleScript to interact with the Mail app on your Mac. All data stays local on your machine.

Related MCP server: macos-mail-mcp

Quick Start

Using Claude Code (Easiest)

If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:

Install the sweetrb/apple-mail-mcp MCP server so you can help me manage my Apple Mail

Claude will handle the installation and configuration automatically.

Or register it deterministically in one command:

claude mcp add apple-mail -s user -- npx -y apple-mail-mcp

Using the Plugin Marketplace

Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:

/plugin marketplace add sweetrb/apple-mail-mcp
/plugin install apple-mail

This method also installs a skill that teaches Claude when and how to use Apple Mail effectively.

Configuring IMAP/SMTP for a plugin install: a plugin install has no editable env block, so supply settings via the config file at ~/Library/Application Support/apple-mail-mcp/config.json — Method B in the IMAP / SMTP Setup Guide. Passwords stay in the macOS Keychain; run the doctor tool to verify.

Using the Codex Marketplace

See Apple Mail in Codex for setup and diagnostics, and the guided setup and OAuth proposal for proposed future authorization support.

Install the same public marketplace in Codex:

codex plugin marketplace add sweetrb/apple-mail-mcp
codex plugin add apple-mail@apple-mail-mcp

The Codex package includes a portable codex/plugin.json, typed stdio server configuration in codex/mcp.json, the Apple Mail skill, and the existing assets. It retains codex/.codex-plugin/plugin.json and codex/.mcp.json for compatible older hosts. Both layouts register the same apple-mail MCP identity through npx -y apple-mail-mcp@<plugin version>. Release synchronization updates both runtime pins and manifest metadata; tests and CI reject drift. An unreleased candidate can be discovered locally, but its exact npm version must be published before that pinned launcher can be installed from the registry.

For ongoing upstream updates, keep the Git marketplace configured. After a new release is published, refresh its catalog:

codex plugin marketplace upgrade apple-mail-mcp

Install the published plugin version from the refreshed marketplace, then start a new Codex session. The refresh does not replace the runtime pin with @latest; the plugin and its pinned npm runtime must refer to the same available release.

The standalone plugin archive bundles the server and requires only Node.js 20+ on the Mac; it does not fetch a runtime from npm. Download it from the release assets, or use the candidate artifact attached to a successful CI run. See Standalone plugin archive for the distribution format and local build command.

An imported archive or separately uploaded private account plugin is a snapshot, not a subscription to this repository's releases. Updating that copy requires a replacement package. When switching to the maintained marketplace distribution, preserve settings and approvals, verify Mail access and reply behavior, then remove the redundant installation. See Updates and migration.

For a personal build, you may explicitly supply a local PNG: node scripts/package-codex-plugin.mjs /path/apple-mail.tar.gz --icon /path/icon.png. The optional image must be square, noninterlaced, 48–2,048 pixels per side, and at most 4 MiB. It is bundled inside the skill's assets directory and used for the generated portable and compatibility manifests' light/dark logo and composer icons. Source manifests, the runtime, and default artwork remain unchanged; omitting --icon preserves the standard archive. No image is fetched automatically. Supply only artwork you have permission to use and distribute; this option does not grant rights to Apple or other third-party artwork, or guarantee that a host will refresh an existing listing's cached presentation.

The compose tools accept composition: "native-editor" to insert new prose through Mail's visible editor, leaving its signature and reply history intact. This opt-in path uses existing macOS Accessibility and Automation permissions; it does not require a separate computer-control plugin. It verifies the composer and sender, preserves the clipboard, and stops without sending if insertion cannot be verified. See native composition for setup, examples, and verification limits. Existing SMTP and AppleScript behavior is unchanged when the option is omitted.

Other Hosts (Hermes, Antigravity)

Two more hosts can run the same apple-mail MCP server (npx -y apple-mail-mcp):

• Hermes Agent (NousResearch) — Hermes has no plugin/marketplace drop-in, so there is nothing in this repo to install from. Register the server with the CLI:

  hermes mcp add apple-mail --command npx --args -y apple-mail-mcp

  Or add it to ~/.hermes/config.yaml by hand:

  mcp_servers:
    apple-mail:
      command: npx
      args: ["-y", "apple-mail-mcp"]

  Restart your Hermes session afterward so the tools load.

• Antigravity (Google) — add the server entry from .antigravity-plugin/mcp_config.json to ~/.gemini/config/mcp_config.json (or via Antigravity's MCP settings).

Manual Installation

1. Install the server:

npm install -g apple-mail-mcp

2. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "npx",
      "args": ["apple-mail-mcp"]
    }
  }
}

3. Restart Claude Desktop and start using natural language:

"Show me my unread emails"

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 — 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

• 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.

• Apple Mail - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)

Features

Messages

Read/list/get tools also return structured JSON (structuredContent) alongside the text, so agents can consume results without parsing prose.

Mailbox & Account Management

Rules, Contacts & Templates

Diagnostics

MCP resources & prompts

Resources expose read-only context the client can attach without a tool call: mail://accounts, mail://templates, and mail://mailboxes/{account}. Prompts package common workflows: triage-inbox, compose-reply, weekly-summary.

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Message Operations

search-messages

Search for messages matching criteria. Searches all accounts by default.

Returns: List of matching messages with ID, date, subject, sender, read state, and flagColor when flagged with an explicit color.

Flag color as a label (#286). Every row from both backends carries flagColor (the palette name — red, orange, yellow, green, blue, purple, gray) whenever the message is flagged with an explicit color; omitted for an unflagged message or one flagged with Mail's plain default (no color chosen). Combined with the flagColor filter above, a colored flag works as a label across mailboxes: flag a set of messages with flag-message/batch-flag-messages, then find exactly that set later with search-messages, without moving anything into a dedicated folder. Known limitation, inherent to Apple's $MailFlagBit0/1/2 IMAP wire encoding, not specific to this server: red (palette index 0) sets no keyword bits, so over IMAP it is indistinguishable from a plain colorless flag, both when reading flagColor back and when filtering on it. AppleScript-backed accounts are unaffected (Mail's own flag index property is 0 for red, -1 for none).

⚠️ Row dates. Since 2.19.7 every row — on both the IMAP and AppleScript backends — carries both dateSent (the message's Date: header) and dateReceived (mailbox arrival — IMAP INTERNALDATE or Mail's date received). They differ legitimately by transit time; when they differ by years, the mailbox was migrated or re-imported and the arrival timestamp was reset — trust dateSent for chronology (#224). dateSent is omitted (not invented) when the message carries no parseable Date: header, or when it is more than 7 days later than dateReceived — Mail substitutes a timestamp of its own for a Date: header it cannot parse (#234).

Large mailboxes & partial results. Apple Mail's AppleScript bridge cannot search very large IMAP/Gmail mailboxes (tens of thousands of messages) before the Apple Event times out — empirically even reading the newest 20 messages of a 44k-message mailbox takes ~45s. To avoid burning minutes only to return a misleading empty result, an unscoped (all-mailboxes) search skips mailboxes whose message count exceeds a threshold (default 5000), enforces a per-account time budget, and reports anything it skipped or that timed out rather than silently returning nothing. When coverage is incomplete the result includes an explicit warning, e.g.:

⚠️  Partial results — this is NOT a confirmed "no such mail":
  - skipped mailbox(es) too large to search via AppleScript: Gmail / All Mail (44287) — scope the search with `mailbox` + a `dateFrom`/`dateTo` window to target them

To search inside a large mailbox, scope the call with mailbox (and ideally a dateFrom/dateTo window). Tune or disable the skip threshold with the APPLE_MAIL_MAX_SEARCH_MAILBOX environment variable (default 5000; set to 0 to disable the guard and attempt every mailbox regardless of size). (#24)

Envelope Index search (opt-in, read-only). For accounts with no IMAP config, set APPLE_MAIL_MCP_ENVELOPE_INDEX=1 to answer header searches (query, from, subject, read/flagged state, dates, mailbox) from Mail's own on-disk Envelope Index instead of an AppleScript scan, so large mailboxes are searched completely rather than skipped. It needs Full Disk Access for the server's Node runtime and opens the database read-only. Anything the index can't answer completely (a flagColor filter, an unknown mailbox, no Full Disk Access, an unrecognised schema, or a corrupt or locked database) falls back to the AppleScript scan. The backend field below reports which one answered. (#342)

Body search for AppleScript-only accounts (opt-in local body index). Without IMAP, search-messages can't search message bodies (AppleScript would have to pull every body through Mail), so a body query reports those accounts as not searched. Set APPLE_MAIL_MCP_BODY_INDEX=1 together with APPLE_MAIL_MCP_ENVELOPE_INDEX=1 to search them through a local full-text index of the .emlx files Mail already keeps on disk. (#349)

• What it reads, and what it needs. Message files under ~/Library/Mail, read only; the mail store is never written. Like the Envelope Index backend, it needs Full Disk Access for the app that runs the server (its Node runtime). doctor reports when it can't read the store, with the same wording.

• Where the index lives. ~/Library/Application Support/apple-mail-mcp/body-index.db (plus -wal, -shm and .writer-lock next to it); set APPLE_MAIL_MCP_BODY_INDEX_FILE to move it. The directory is created 0700 and the files 0600. The index is contentless: it stores the search tokens, not a copy of any message, but the tokens still reveal a lot about your mail — treat the file as sensitive. Expect roughly 70 MB per 22,000 messages.

• Deleting it. Turn the flag off (or stop the server), then delete the files:

  rm -f ~/Library/Application\ Support/apple-mail-mcp/body-index.db*

  It is only a cache; with the flag on it is rebuilt from scratch on the next start.

• First build and upkeep. One server instance (the first to start) builds and updates the index in the background in small slices; other instances — one per conversation in some hosts — search it read-only and take over if that instance exits. The walking and parsing run in a short-lived child process (the same build/index.js on the same Node runtime, so the same Full Disk Access grant applies), which exits as soon as it has caught up: the server stays responsive during a build, and the memory parsing takes goes back to the system instead of staying with the server. If that process can't start or can't read the store, the server builds on its own main thread instead and doctor says why (and tries a build process again an hour later). A build process that stops responding for a minute is stopped and restarted. New mail is picked up through file-system events within seconds, with a full check every 10 minutes as a safety net. A build of ~22,000 messages took about 40 s on an Apple-silicon Mac.

• Coverage is always reported. A body search never presents an incomplete index as "no matches". Messages in the searched scope that it couldn't read in full are counted, and the result is partial: true with a notSearchedMailboxes entry such as Google / * (1,234 messages not downloaded, 12 not indexed yet). Not downloaded means Mail has only the headers (common for older mail on IMAP/Exchange accounts set to download recent messages only); open those messages in Mail, or change the account's download setting, to make them searchable. Messages over 25 MB are not read.

• Requirements. Node 22.5 or later (for node:sqlite); on older runtimes the feature turns itself off and says why in the logs and doctor.

Coverage diagnostics (structured fields). The warning above is prose for a human reader; the same information is also returned as structured fields on search-messages and list-messages, so a caller can tell "nothing matched" apart from "I did not look everywhere" without parsing the text:

Deadline and cancellation (#276). Tool calls run one at a time (so they cannot race into Mail.app), which means a long search holds every later call behind it. An IMAP search-messages therefore stops at APPLE_MAIL_MCP_SEARCH_DEADLINE_MS (default 45000, minimum 2000, measured from when the request arrived — time queued behind other calls counts) and returns what it found plus timedOutMailboxes, and it stops the same way when the client cancels the request. The mailbox being searched at that moment is abandoned by closing its IMAP connection (the next call reconnects), so the queue is released promptly rather than after a server-side SEARCH that can take a minute and a half on a very large mailbox. A request cancelled while still queued is skipped. Keep the deadline below your client's own request timeout.

Treat a non-empty skippedLargeMailboxes as actionable rather than informational: re-run scoped to the named mailbox with a dateFrom/dateTo window, or configure the IMAP backend, which searches those mailboxes server-side. The list fields are optional and are omitted (or empty) when coverage was complete.

A row the IMAP backend could only read with a reduced item set (its full BODYSTRUCTURE, or its whole FETCH response, was unparseable — e.g. a message forwarded as an attachment many levels deep) is still returned, with a metadataIncomplete note saying what was missing; its hasAttachments is then inferred from the top-level Content-Type.

get-message

Get the full content of a message.

Returns: Subject line and message body (plain text by default, HTML if preferHtml is true and HTML content is available). structuredContent also carries rfcMessageId and, since 2.19.0, two dates: dateSent (the message's Date: header — Mail's date sent) and dateReceived (arrival in the mailbox — Mail's date received / IMAP INTERNALDATE). They differ legitimately by transit time; when they differ by years, the mailbox was migrated or re-imported and the arrival timestamp was reset — trust dateSent for chronology (#224). Since 2.19.6 dateSent is omitted when it is more than 7 days later than dateReceived: a message cannot be sent after it arrived, and Mail.app substitutes a timestamp of its own for a Date: header it cannot parse (#234). isHtml reports what was actually returned — a message with no text/plain part returns its HTML part with isHtml: true. Bodies are decoded by each part's declared charset, falling back to windows-1252 for bytes that are not valid UTF-8.

Numeric ids — how the message is found (#270): with account + mailbox the read opens that one mailbox and stops there. Otherwise it opens the mailbox the id was last listed or searched from. A stale remembered location is forgotten before a bounded scan, but an ambiguous remembered account or mailbox stops without a scan. That cross-mailbox scan skips any mailbox holding more than APPLE_MAIL_MAX_BYID_SCAN_MAILBOX messages (default 50000; 0 disables the guard) and stops after ~9s, because Mail's whose id is probe costs seconds per hundred thousand messages; a miss then names the mailboxes it skipped and, if it stopped early, the ones it never reached. A mailbox whose size count does not answer within 3s is remembered — on disk, for 7 days, across restarts (APPLE_MAIL_MCP_STALLED_MAILBOXES_FILE, default ~/Library/Application Support/apple-mail-mcp/stalled-mailboxes.json; delete it to forget) — and never counted again, since Mail.app keeps working on an abandoned count and everything after it would queue; the scan stops the moment such a count times out rather than queue behind it. If Mail.app is not running these reads say so instead of launching it. Pass account + mailbox to read from one of those, or use the message's imap: id, which never scans. The same resolution backs get-message-headers, get-thread's seed lookup, and the original-message read of reply-to-message / forward-message and the attachment tools.

Large messages / attachments: reading a full message routes through osascript, whose captured output buffer defaults to 64 MB. Override it with the APPLE_MAIL_MCP_MAX_BUFFER environment variable (in bytes) if you work with messages whose raw MIME (e.g. a large embedded attachment) exceeds that — a value below the message size makes the read fail with a buffer-overflow error rather than truncating (#27).

get-message-headers

Return a message's raw RFC 5322 header block — without fetching the body or any attachment — plus the parsed fields chronological and threading work needs. Added in 2.19.0 for mailboxes whose arrival timestamps were reset by a migration (#224): the Date: header is the author's send time and survives such moves; INTERNALDATE / date received does not.

Returns: The raw header block as text. structuredContent carries raw, every header as ordered headers[] ({name, value}, folded lines joined, duplicates such as Received: kept in wire order, values left RFC 2047-encoded), headerCount, and the decoded key fields: date (ISO 8601, from the Date: header), dateHeader (verbatim), dateReceived (mailbox arrival time — IMAP INTERNALDATE or Mail's date received), messageId, subject, from, to, cc, replyTo, inReplyTo, references[] and received[] (first entry = last hop). Fields the message does not carry are omitted. backend says which backend read the block ("imap" or "applescript"), and warnings[] appears when a malformed block was repaired (#234).

Backends (get-message-headers): an imap: id reads the first 64 KiB of BODY.PEEK[] over IMAP and cuts the header block out of it (cheap even for a 20 MB message). That is deliberate: iCloud rewrites 8-bit header bytes to * in ENVELOPE and BODY[HEADER], and only BODY[] returns them as stored; each line is decoded as UTF-8, falling back to windows-1252, so a raw latin-1 display name survives. A header block larger than the window falls back to BODY.PEEK[HEADER]. A numeric id reads Mail's all headers property over AppleScript, with the same mailbox-scoped fast path as get-message. ⚠️ That property is Mail's own rendering, not the stored bytes: for a Date: value Mail cannot parse it drops the value and joins the next header onto the name (Date: Subject: …). The tool splits that back apart, reports the date as absent rather than as a Subject string, and says so in warnings[]; the imap: id for the same message has the real Date:.

get-message-rfc822

Acquire a message's complete original RFC 822 bytes exactly as the IMAP server stores them, together with the IMAP identity that links the copy back to its source (#244). Built for archival, forensic review and evidence preservation: nothing is decoded, charset-converted, line-ending-normalized or MIME-re-serialized, and the SHA-256 is computed over exactly the bytes returned. IMAP-only — it needs an imap: id, i.e. an IMAP-configured account (docs/IMAP-SETUP.md). There is no AppleScript path on purpose: Mail's bridge exposes its own rendering of a message, not the stored bytes.

Returns: a one-line summary as text. structuredContent carries the acquisition record: account, mailbox, uid, uidValidity (decimal string), internalDate (ISO 8601 INTERNALDATE — arrival, not the Date: header), flags[], size (the server's RFC822.SIZE), bytes (the count actually acquired and hashed), sha256 (hex, over exactly those bytes), messageId (from ENVELOPE, for convenience — the authoritative copy is in the bytes), readMethod (the IMAP commands issued), backend: "imap" and warnings[] — plus contentBase64 in inline mode or savedPath in file mode. The base64 is carried only in structuredContent; the text block never repeats it.

Read-only by construction. The mailbox is opened with EXAMINE and the body fetched with BODY.PEEK[], so \Seen is not set and no STORE, COPY, MOVE, APPEND or EXPUNGE is issued. No Mail.app, AppleScript or osascript is involved. The only side effect is the optional file, created with wx (an existing file or symlink is refused, never overwritten) and mode 0600, and only inside the allowed roots — the same policy as save-attachment.

Sizes. The inline ceiling exists because the MCP stdio transport drops any single message over 10 MB with no error text: 6 MiB of raw bytes is 8 MiB of base64. maxBytes is a ceiling, not a cut — an oversize message is refused with its RFC822.SIZE, so you can choose between raising maxBytes (inline, up to 6 MiB) and savePath (up to 25 MiB). warnings[] reports an RFC822.SIZE that disagrees with the byte count actually received (the hash still covers what was received) and a server that reported no UIDVALIDITY.

Verifying a derivative. shasum -a 256 file.eml must equal sha256. account + mailbox + uidValidity + uid is the durable pointer back to the source message — a UID on its own is meaningful only for one UIDVALIDITY, which the server may change (typically on a mailbox rebuild).

list-messages

List messages in a mailbox.

Returns: List of messages with ID, date, subject, sender, and flagColor when flagged with an explicit color (see the flag-color note under search-messages, which also supports filtering by it).

⚠️ Row dates. Since 2.19.7 every row — on both the IMAP and AppleScript backends — carries both dateSent (the message's Date: header) and dateReceived (mailbox arrival — IMAP INTERNALDATE, falling back to the header date if the server withholds it; Mail's date received on the AppleScript path). They differ legitimately by transit time; when they differ by years, the mailbox was migrated or re-imported and the arrival timestamp was reset — trust dateSent for chronology (#224). Since 2.19.6 the IMAP dateSent is recovered even when the server's own parse of the Date: header failed (legacy locale dates such as jue ago 30 13:55:12 2007); both backends omit dateSent (rather than reporting it) when it is more than 7 days later than dateReceived (#234). Before 2.19.7 the AppleScript path carried only dateReceived. Sort order keys on the header date on both backends, which is the stable one.

send-email

Send a new email immediately.

⚠️ Safety: Sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling.

Example:

{
  "to": ["colleague@company.com"],
  "subject": "Meeting Tomorrow",
  "body": "Hi, just confirming our meeting at 2pm tomorrow.",
  "account": "Work",
  "attachments": ["/Users/me/Documents/agenda.pdf"]
}

Threading headers (inReplyTo / references)

send-email and create-draft accept caller-built threading headers (2.20.0, #267) for callers that compose the recipients and quoted text themselves. Prefer reply-to-message — it derives recipients, In-Reply-To/References and the quote from the original, and (since 2.20.0) takes attachments too.

• Each value must be a single RFC 5322 msg-id token with angle brackets (<left@right>, no whitespace); anything else is rejected by validation.

• The headers are always emitted as plain <id> tokens — never RFC 2047-encoded, even for Outlook/Exchange IDs longer than 76 characters (a long header is folded at whitespace between tokens, which is legal and does not alter the id).

• Mail.app's AppleScript cannot set these headers, so they are never silently dropped: send-email refuses them unless the SMTP transport is in use, and create-draft files a threaded draft over IMAP instead of through Mail.app (below).

SMTP transport

On macOS 15+ (Sequoia/Tahoe), Mail.app wraps any AppleScript-injected body in <blockquote type="cite"> under the Apple-Mail-URLShareWrapperClass template, so emails sent through the default applescript transport render to recipients as if they were quoted/forwarded (Apple radar FB11734014, open since Ventura). The SMTP transport bypasses Mail.app entirely and submits clean MIME directly. Once SMTP is configured, send-email uses it automatically (no need to pass transport per call); pass transport: "applescript" to force the Mail.app path.

Two differences to know when SMTP is auto-preferred:

• Sent-folder copy is best-effort over IMAP. SMTP submission itself never touches IMAP, so since 2.18.0 the server files the sent message into the Sent mailbox of whichever configured IMAP account's login matches the SMTP identity (APPLE_MAIL_MCP_IMAP_* mirroring APPLE_MAIL_MCP_SMTP_*), flagged \Seen. The copy carries the same Message-ID that was delivered, so replies thread against it correctly, and it keeps the Bcc header the recipients never see — your own archive is exactly where that belongs. Results report sentCopy: true or sentCopy: false with sentCopyError; the field is absent when no configured IMAP account matches the SMTP identity, which is a skip, not a failure. A copy that fails never fails the send — the mail has already gone. Before appending, the Sent mailbox is searched for that Message-ID; if the submission server already filed it (Gmail's SMTP always does — the server waits up to ~3 s for it there), nothing is appended and the result adds sentCopyAlreadyFiled: true alongside sentCopy: true. Use transport: "applescript" if you want Mail.app itself to file the copy.

• account is a From override, not account selection. Over SMTP, account is used as the From address only when it is an email address; a Mail.app account label (e.g. "Work") can't select an account over SMTP, so a call that passes one is left on the AppleScript path automatically. To force account selection, pass transport: "applescript" explicitly. For sender safety, an email-form override must match the SMTP login user, the configured APPLE_MAIL_MCP_SMTP_FROM, or an address listed in the comma-separated APPLE_MAIL_MCP_SMTP_ALLOWED_FROM; any other From address is rejected before connecting.

Both plain-text and HTML bodies are supported — over SMTP an HTML body (CLI --html-body-file) is sent as multipart/alternative with the plain-text fallback.

Configure SMTP via environment variables on the MCP server. The password is read from the macOS Keychain by default, so no secret goes in config:

Non-implicit-TLS SMTP connections fail closed if STARTTLS is unavailable. APPLE_MAIL_MCP_SMTP_ALLOW_PLAINTEXT=1 is a deliberate escape hatch for a trusted isolated server or test fixture; it disables the upgrade requirement and can expose credentials and message content. The server emits a warning when it is used. Keep the default unset.

Store the password in the Keychain once (an app-specific password for Gmail/ iCloud). A generic-password item with an explicit service name keeps it from colliding with the system mail account password, and matches APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE:

# Fastmail (Keychain service defaults to the host)
security add-internet-password -s smtp.fastmail.com -a you@example.com -w

# Gmail / Google Workspace, using a dedicated Keychain service name:
#   APPLE_MAIL_MCP_SMTP_HOST=smtp.gmail.com
#   APPLE_MAIL_MCP_SMTP_USER=you@gmail.com
#   APPLE_MAIL_MCP_SMTP_KEYCHAIN_SERVICE=apple-mail-mcp-smtp
security add-generic-password -s apple-mail-mcp-smtp -a you@gmail.com -w

Once the env vars are set, a plain send-email (no transport) already goes out clean:

{
  "to": ["colleague@company.com"],
  "subject": "Standings",
  "body": "Plain body — no blockquote wrapping."
}

apple-mail-send CLI (no MCP server required)

The package also installs an apple-mail-send binary — a standalone CLI over the same SMTP path, for cron jobs, scheduled tasks, and scripts that can't run an MCP session. It reads the identical APPLE_MAIL_MCP_SMTP_* env + Keychain config:

apple-mail-send \
  --from you@example.com --to colleague@company.com \
  --subject "Standings" --body-file /tmp/body.txt \
  [--html-body-file /tmp/body.html] [--attach /tmp/report.pdf]

Repeatable --to/--cc/--bcc/--attach; an --html-body-file is sent as a multipart/alternative alongside the plain --body-file. Exit codes follow sysexits.h: 0 success, 64 usage error, 66 unreadable body file, 78 SMTP not configured.

IMAP backend — opt-in

📘 For step-by-step setup (app passwords, Keychain, config methods, multi-account, upgrading, troubleshooting), see the IMAP / SMTP Setup Guide. The summary below is the reference; the guide is the walkthrough.

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), and its delete/rename mailbox and draft handlers don't work on server-side accounts at all (#42). When an account is configured for IMAP, the MCP routes to a server-side IMAP backend (#43) that is fast and correct on exactly those mailboxes. This is opt-in and additive: any account without IMAP configured behaves exactly as before (AppleScript).

What routes to IMAP when an account is IMAP-configured:

• Read: search-messages, list-messages (server-side SEARCH, typically sub-second), and get-message.

• Folder ops: create-mailbox, rename-mailbox, delete-mailbox — IMAP's CREATE/RENAME/DELETE succeed on the iCloud/Gmail/Workspace/Exchange mailboxes Mail.app's AppleScript bridge can't touch (#42).

• Message mutations: mark-as-read/unread, flag-message/unflag-message, move-message, delete-message.

• Batch mutations (2.1): batch-mark-as-read/unread, batch-flag/unflag-messages, batch-move-messages, batch-delete-messages — imap: ids are grouped by mailbox and applied as a single UID STORE/UID MOVE; numeric ids in the same batch still use AppleScript.

• Counts & stats (2.1): get-unread-count and list-mailboxes use STATUS; get-mail-stats uses STATUS + SEARCH SINCE — authoritative and fast even on huge mailboxes. As of v2.6.0 these prefer IMAP whenever it's configured (see Read routing below), merging across accounts when no account is given.

• Attachments (2.1): list-attachments, save-attachment, fetch-attachment use BODYSTRUCTURE + FETCH BODY[part] for imap: ids — faster and able to see MIME-embedded attachments AppleScript misses.

• Threading (2.1): get-thread links a conversation via References/Message-ID (HEADER SEARCH) for an imap: seed, falling back to subject grouping otherwise.

Message ids are backend-tagged. The IMAP read path emits self-describing ids of the form imap:<token> (the token encodes the account, mailbox path, and UID). Pass that id back to get-message, a message mutation, a batch op, or the attachment/thread tools and it routes to IMAP automatically; bare numeric ids continue to use AppleScript. So an agent never has to know which backend a message came from — the id carries it.

Read routing (v2.6.0): reads PREFER direct IMAP whenever IMAP is configured. The read tools — search-messages, get-thread, list-messages, list-mailboxes, get-unread-count, get-mail-stats — now go to IMAP whenever any APPLE_MAIL_MCP_IMAP_* account is configured, not just when an explicit matching account is passed. There are three cases:

• Explicit IMAP account — single-account IMAP (fast server-side path).

• Explicit non-IMAP account — AppleScript (that account isn't on IMAP).

• No account given — merge across all accounts: the query fans out over every configured IMAP account, and AppleScript runs only for the accounts no IMAP config covers (the account list is partitioned — accounts already served by IMAP are not re-scanned via AppleScript). If every Mail account is IMAP-configured, AppleScript is skipped entirely. The results are merged so no account is dropped. Message lists still de-duplicate as a safety net (preferring the IMAP copy, which carries the round-trippable imap: id) and sort newest-first; count tools (get-unread-count, get-mail-stats) count each account via exactly one backend so a coverage mismatch can never double- (or under-) count.

  • An omitted mailbox on search-messages searches the account's entire store, not just one default folder (v2.17.1, #199). Per account, the fan-out uses the server-advertised RFC 6154 \All mailbox when one exists (Gmail/Workspace's [Gmail]/All Mail); otherwise it searches every selectable mailbox the server lists (iCloud, generic IMAP), merges the matches, de-duplicates by Message-ID, and sorts newest-first before applying limit/offset. A mailbox that can't be selected or searched is named in the result instead of silently dropping coverage. Scanning every mailbox on a large, deeply-nested account costs one SEARCH + a bounded FETCH per mailbox over the pooled IMAP connection — pin a mailbox to skip the fan-out when you already know where to look. list-messages (no query) still defaults an omitted mailbox to INBOX on every provider — only unscoped search scans the whole account.

If IMAP is not configured at all, every read behaves exactly as before (pure AppleScript). The three mailbox-write ops (create-mailbox, delete-mailbox, rename-mailbox) remain conservative — they route to IMAP only for an explicitly-named IMAP account, never on an omitted account.

Multiple IMAP accounts (C2): set APPLE_MAIL_MCP_IMAP_ACCOUNTS to a JSON array, e.g. [{"account":"Work","user":"me@co.com","host":"imap.co.com","keychainService":"imap.co.com"}]. Each entry accepts account, user, host, port, password, keychainService, keychainAccount. Calls route to the account matching their account argument (or the decoded imap: id), and each account keeps its own pooled connection.

Non-implicit-TLS IMAP connections require STARTTLS and fail closed when the server does not offer a usable upgrade. APPLE_MAIL_MCP_IMAP_ALLOW_PLAINTEXT=1 is a deliberate escape hatch for a trusted isolated server or test fixture; it disables the upgrade requirement and can expose credentials and message content. Keep the default unset.

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: IMAP connections are pooled — one kept-alive connection per account is reused across calls (verified with a NOOP, closed after APPLE_MAIL_MCP_IMAP_IDLE_MS of inactivity), so there's no per-call connection overhead (#50).

iCloud: set APPLE_MAIL_MCP_IMAP_HOST=imap.mail.me.com, APPLE_MAIL_MCP_IMAP_USER to your iCloud address, APPLE_MAIL_MCP_IMAP_ACCOUNT to the Mail account name (e.g. iCloud), and use an app-specific password (from appleid.apple.com) stored in the Keychain.

Connection footprint (playing nice with Gmail)

IMAP connections are a shared, capped resource: Gmail allows at most 15 simultaneous IMAP connections per account, and Apple Mail itself needs some of those slots. This server keeps its footprint small:

• One pooled connection per account, reused across calls and closed after ~30s idle (tune with APPLE_MAIL_MCP_IMAP_IDLE_MS; 0 = never close). So a server that isn't actively serving IMAP calls holds zero connections.

• IMAP IDLE is opt-in (APPLE_MAIL_MCP_IMAP_IDLE=1). When on, it adds one persistent connection per account (a long-lived watcher), on top of the pooled request connection — leave it off if you don't need push notifications.

• Connections are dropped on shutdown — SIGINT/SIGTERM and stdin-EOF (the MCP client/parent going away). As of v2.6.1 the server also self-exits if it becomes orphaned (parent force-quit/crashed → reparented to launchd), polling every 30s, so it can't linger holding sockets after its session is gone.

The catch is multiple concurrent instances. A host like the Claude desktop app spawns a separate set of MCP servers per open conversation (and respawns them after a crash), so the footprint is per instance × accounts. With IDLE off, an idle instance trends to 0 connections; with many active conversations or IDLE on, the per-account total climbs toward Gmail's 15-connection cap and can starve Apple Mail of slots (→ intermittent "cannot connect"). If you hit that, close idle Claude conversations, keep APPLE_MAIL_MCP_IMAP_IDLE off unless you need push, and/or lower APPLE_MAIL_MCP_IMAP_IDLE_MS.

Configuration file (when the host strips env)

Some host apps (e.g. Claude Desktop) launch the MCP server with a scrubbed environment and ignore the env block in their server config, so there's no way to pass APPLE_MAIL_MCP_* settings through it. In that case, put them in a JSON file the host doesn't manage — APPLE_MAIL_MCP_CONFIG_FILE, or by default ~/Library/Application Support/apple-mail-mcp/config.json:

{
  "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
  "APPLE_MAIL_MCP_IMAP_HOST": "imap.gmail.com",
  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
  "APPLE_MAIL_MCP_IMAP_KEYCHAIN_ACCOUNT": "you@gmail.com",
  "APPLE_MAIL_MCP_IMAP_IDLE": "1"
}

The server reads it at startup and merges values into the environment without overriding anything already set there (so an explicit env still wins). Store only non-secret config here — passwords belong in the Keychain, never in this file.

Push notifications (IMAP IDLE) — opt-in

When APPLE_MAIL_MCP_IMAP_IDLE=1, the server opens a dedicated, long-lived connection to each configured IMAP account and watches its INBOX for new mail. On arrival it pushes two MCP notifications to the client (no polling by the client required):

1. notifications/message (logging) — a human-readable line, e.g. New mail in "Work": 2 new message(s) (INBOX now 1843).

2. notifications/resources/updated — for the affected account's resource mail://mailboxes/{account}, so a client subscribed to that resource knows to re-read it.

This requires an IMAP account to be configured (single-account env or APPLE_MAIL_MCP_IMAP_ACCOUNTS); accounts that only use AppleScript aren't watched. Detection is real-time via the IMAP IDLE EXISTS event where the server pushes it, with an automatic polling fallback for servers that don't. Dropped connections reconnect with backoff, and the watchers shut down cleanly on SIGINT/SIGTERM.

Enable it in your MCP client config alongside the IMAP settings:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/apple-mail-mcp/build/index.js"],
      "env": {
        "APPLE_MAIL_MCP_IMAP_USER": "you@gmail.com",
        "APPLE_MAIL_MCP_IMAP_KEYCHAIN_SERVICE": "imap.gmail.com",
        "APPLE_MAIL_MCP_IMAP_IDLE": "1"
      }
    }
  }
}

Note: this is most useful with clients that surface MCP logging messages or subscribe to resource-update notifications. Clients that ignore notifications are unaffected — the feature is opt-in and adds no behavior unless enabled.

send-serial-email

Send individual personalized emails to a list of recipients (mail merge). Each recipient receives their own email — recipients don't see each other. Supports {{placeholder}} tokens in both subject and body.

Each recipient object:

Example:

{
  "recipients": [
    { "email": "alice@example.com", "variables": { "Name": "Alice", "Company": "Acme" } },
    { "email": "bob@example.com", "variables": { "Name": "Bob", "Company": "Globex" } }
  ],
  "subject": "Hello {{Name}}!",
  "body": "Dear {{Name}},\n\nGreat to connect about {{Company}}.\n\nBest regards"
}

Returns: Per-recipient success/failure results with a summary count, plus the transport used for the batch.

⚠️ Safety: Sends real mail immediately to every recipient and cannot be unsent. Confirm the recipient list, subject, and body with the user before calling.

create-draft

Save an email to Drafts without sending.

Returns: Confirmation that draft was created, with transport (applescript, or imap for a threaded draft).

Threaded drafts (2.20.0, #267): Mail.app's outgoing message has no header property, so a draft with inReplyTo/references cannot go through AppleScript. Instead the server composes it with the same MIME builder as the SMTP send (attachments included) and files it over IMAP into the account's Drafts mailbox (SPECIAL-USE \Drafts), flagged \Draft. The account is account when given (it must be a configured IMAP account — pass the exact accountLabel or login from list-accounts/your APPLE_MAIL_MCP_IMAP_* config, e.g. "user@icloud.com"; a generic provider name like "iCloud" is not a recognized alias and is refused); otherwise the IMAP account whose login is the SMTP identity, else the only configured IMAP account. When none qualifies — IMAP unconfigured, an unknown account, or several accounts and no way to choose — the call fails and files nothing; it never falls back to an unthreaded Mail.app draft. The result names the Drafts mailbox, the account and the draft's messageId. Without threading headers, create-draft is unchanged (AppleScript).

get-thread

Group a conversation by normalized subject (across the AppleScript or IMAP backend).

Returns: The conversation's messages, oldest-first.

fetch-attachment

Return an attachment's bytes as base64 (the read counterpart to inline-base64 send).

Returns: The attachment bytes, base64-encoded (also in structuredContent.contentBase64).

resolve-message-id

Map imap: message IDs to their numeric Mail.app IDs, via each message's RFC 5322 Message-ID (the join key both backends share). Needed for the AppleScript reply/forward path; direct SMTP replies and forwards read imap: IDs without numeric conversion. Numeric IDs pass through unchanged.

Returns: For each input ID, its numericId (or null when it can't be resolved) and the messageId used, plus count and resolvedCount. The lookup scopes to the message's account and checks its INBOX first, to avoid scanning a large All Mail/Archive mailbox.

You do not need this for flag colors (v2.10.0+). Colors used to require the numeric-ID path, and older docs and tool descriptions said so. flag-message and batch-flag-messages now write the color over IMAP directly, as Mail.app's $MailFlagBit0/1/2 keywords, so a smart mailbox keyed on flag color matches an IMAP-flagged message. Resolving IDs just to apply a color reintroduces the AppleScript/TCC dependency 2.10.0 removed. Flag, move, mark, and delete all accept imap: IDs as-is.

reply-to-message

Reply to an existing message.

Example - Reply to sender only:

{
  "id": "12345",
  "body": "Thanks for the update!"
}

Example - Reply all, save as draft:

{
  "id": "12345",
  "account": "Work",
  "mailbox": "INBOX",
  "body": "I'll review this and get back to everyone.",
  "replyAll": true,
  "send": false
}

Example - Reply all with an attachment (2.20.0):

{
  "id": "imap:eyJhIjoiV29yayIsInAiOiJJTkJPWCIsInUiOjQyfQ",
  "body": "Here is the PDF you asked for.",
  "replyAll": true,
  "attachments": [
    "/Users/me/Documents/quote.pdf",
    { "filename": "notes.txt", "contentBase64": "SGVsbG8K" }
  ]
}

Attachments (2.20.0, #267): same schema, limits (20 items, 25 MiB each) and read roots as send-email, validated before the original is fetched — an out-of-roots path fails with exactly send-email's error. Recipients, threading headers and the quote are identical to the same call without attachments. Over SMTP the files ride the same nodemailer path send-email uses, so the Sent-folder copy (sentCopy) carries them too. On the AppleScript transport they are added with make new attachment after the reply content is set and before save/send (inline items are written to 0600 temp files and removed afterwards), so a send: false draft contains both the attachments and the quoted original. make new attachment returns before Mail has loaded the file, so the script waits until Mail counts every file (bounded at 15 s) before saving or sending (2.20.16, #293; the same wait applies to send-email and create-draft). Results report attachmentCount.

Delivery: imap: IDs are read directly from their encoded account, mailbox, and UID. Numeric IDs are read through Mail.app. With SMTP configured, replies use clean MIME with the original Message-ID in In-Reply-To and the full References chain. Only the original plain-text body is quoted; the new text is not. Pass transport: "smtp" to require this path, or transport: "applescript" to use Mail.app explicitly.

Numeric source scope: Pass account and mailbox together using the account and full mailbox path from the original search or listing. Both the original read and the Mail reply target use that scope; a missing or ambiguous account, mailbox, or message stops the operation instead of scanning elsewhere. For Mail.app composition, the original must have a usable Message-ID, which is checked again against the selected message before the composer is created. An imap: ID already encodes its source: omit both fields for that form. Supplying only one field, or supplying either with an imap: ID, returns an error. Without explicit scope, numeric IDs retain the remembered-location and bounded-scan strategy described under numeric IDs, but an ambiguous remembered account or mailbox now stops instead of falling back to a scan. For scoped SMTP, the configured From address must belong to the selected enabled Mail account; an SMTP login can be a separate service username. A local "On My Mac" source has no Mail account whose SMTP From can be verified, so scoped SMTP stops rather than selecting an identity.

AppleScript transport quoting (v2.19.12): every draft (send: false) and any send that falls back to AppleScript (SMTP not configured) also gets the original quoted — an "On <date>, <sender> wrote:" attribution line followed by the > -prefixed original body, built the same way as the SMTP path. Mail's own reply/forward AppleScript commands generate this quote internally but expose no way to read it back, so it's built here instead of relying on Mail's (unreadable) copy. Unlike SMTP, this path has no sending-identity restriction — it's read-only source lookup, not sending.

Sender on the AppleScript transport (2.20.15, #294): Mail's reply/forward commands set no sender, so Mail would answer from its default sending account. The reply or forward is now sent from the account the original sits in: the original's to/cc address that belongs to that account — or, for a message you sent, its own From address — else the account's first address. The sender is read back before saving or sending; a mismatch deletes the compose and returns an error. A message in an "On My Mac" mailbox has no account, so its recipients are matched against every enabled account and, with no match, the sender is left to Mail. The same applies to forward-message.

Failure behavior: SMTP and AppleScript-content replies stop if the original source or plain-text body cannot be read, rather than silently dropping the quote. Numeric-message replies can recover text from raw MIME when Mail.app's decoded content is unavailable. A genuinely empty original body is allowed; an unreadable body is not. Native-editor mode preserves Mail's own reply history and requires the original source to be readable, but does not reconstruct its plain-text quote. Once SMTP is selected, a missing password, unreadable source, missing reply address or Message-ID, or SMTP failure returns an error. It does not silently switch to AppleScript or create an unthreaded new message. With SMTP unconfigured and transport omitted, AppleScript remains available. send: false saves a Mail.app draft; combining it with transport: "smtp" is rejected before composing.

The direct IMAP source read is bounded to 25 MiB, including MIME attachments. Its account login must match the SMTP login, configured From, or an explicitly configured APPLE_MAIL_MCP_SMTP_ALLOWED_FROM identity; otherwise the call fails rather than sending from an unrelated account. The SMTP configuration still represents a single sending identity, not a per-account SMTP registry.

Success includes transport, attachmentCount and, for SMTP when returned by the server, the new messageId. Over SMTP a best-effort Sent-folder copy is filed over IMAP exactly as for send-email (sentCopy / sentCopyError, see SMTP transport). send-email is for new conversations: adding Re: to its subject does not add threading headers. Use this reply tool with the original id instead.

⚠️ Safety: With the default send: true, sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling (or pass send: false to save a draft for review).

forward-message

Forward a message to new recipients.

Delivery: uses the same source lookup, transport selection, 25 MiB source limit, account-identity check, and failure behavior as reply-to-message. A forward deliberately starts a new conversation, so it has no In-Reply-To or References headers. The existing plain-text forwarding behavior is unchanged: original attachments are not reattached. See SMTP transport. On the AppleScript transport, a body is merged with the forwarded-message header block and original text the same way the SMTP path builds it (see reply-to-message's AppleScript transport quoting note); with no body, Mail's own forward content is left untouched — unless attachments are given, in which case the forwarded-message block is built the same way so Mail has a paragraph to anchor the new files after.

Attachments (2.20.0, #267): attachments adds new files to the forward, with or without a prepended body, under the same rules, validation and per-transport mechanics as reply-to-message's attachments. They are independent of the original's attachments (which the SMTP path still does not reattach).

SMTP forwarding requires a readable plain-text original. Scoped AppleScript-content forwards that add a body or attachments also stop if the original text is unreadable; without added content, Mail retains its own forward history. Native-editor mode preserves Mail's native history. An intentionally empty plain-text message is still valid.

⚠️ Safety: With the default send: true, sends real mail immediately and cannot be unsent. Confirm the recipients, subject, and body with the user before calling (or pass send: false to save a draft for review).

mark-as-read / mark-as-unread

Change read status of a message.

flag-message / unflag-message

Flag or unflag a message. flag-message optionally takes a flag color; unflag-message removes the flag entirely (which also clears any color).

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 back, or find messages by color, use search-messages (or list-messages for read-back only) — both routes now return flagColor (the palette name) on every flagged-with-a-color row, and search-messages takes a flagColor filter using this same palette (#286). The IMAP route additionally still carries the raw 0-6 flagColorIndex for back-compat.

delete-message

Delete a message (move to trash).

structuredContent carries countDelta — what the delete actually did to the source mailbox. See Auditing destructive operations.

⚠️ Safety: Destructive. Requires explicit user confirmation; search/list first to confirm the message id.

move-message

Move a message to a different mailbox.

A destination is matched first as a full path, then as a leaf name. If a leaf name matches more than one mailbox (e.g. Archive under both Work and Thornlands), the move is refused with an error naming every candidate — pass the full path. The same applies to batch-move-messages, delete-mailbox and rename-mailbox.

structuredContent carries countDelta — what the move actually did to the source mailbox. See Auditing destructive operations.

list-attachments

List attachments on a message.

Returns: List of attachments with name, MIME type, and size — the decoded byte count, i.e. what fetch-attachment returns.

A numeric id resolves the same way the read tools resolve one (2.20.21): the mailbox the id was listed from when that is known, else a bounded cross-mailbox scan that skips very large mailboxes and stops at its time budget. An id that several mailboxes hold is refused, with the candidates named, rather than answered for whichever copy came first — so list or search the mailbox you mean immediately before calling this. imap:… ids are never ambiguous.

Sizes over IMAP. BODYSTRUCTURE reports a part's size in its transfer encoding, so a base64 attachment's raw figure is ~4/3 of the file. list-attachments converts it: a Content-Disposition size= parameter wins when present; 7bit/8bit/binary parts are exact as reported; base64 parts are measured exactly from a short tail of each part (padding and line wrap), fetched in one batched FETCH for the whole message; quoted-printable parts up to 64 KiB are fetched and counted exactly. If a part can't be measured (the probe fails, the wrap is irregular, or a quoted-printable part is larger), the size is an estimate within a few bytes for base64 — an upper bound for quoted-printable — and the entry carries sizeApproximate: true. fetch-attachment always reports the exact bytes.

save-attachment

Save a message attachment to disk.

The destination must not already exist: save-attachment fails closed instead of overwriting an existing file. AppleScript and MIME fallback paths stage the bytes privately, commit with an exclusive create, and leave the saved file owner-readable/writable (0600).

A numeric id resolves the same way the read tools resolve one (2.20.21): the mailbox the id was listed from when that is known, else the bounded cross-mailbox scan. An id that several mailboxes hold saves nothing rather than writing some other message's attachment under the name you asked for.

Batch Operations

All batch operations accept an array of message IDs (max 100 per batch) and return per-item success/failure results.

Numeric IDs are scoped to the mailbox you listed them from. Mail.app numbers messages per mailbox, so on a label store (Gmail, iCloud) one message answers to the same id in INBOX, Important and All Mail at once — and deleting the All Mail copy is not the same operation as deleting the INBOX copy. Each id is therefore bound to the mailbox it was listed/searched from and the operation is applied only there, so list or search the mailbox immediately before acting on it. An id the server hasn't seen listed is accepted only when exactly one mailbox holds it; if several do, that id fails with the candidate mailboxes named instead of being applied to an arbitrary copy. imap:… ids carry their own account + mailbox + UID and are never ambiguous.

Say which mailbox with sourceMailbox / sourceAccount. The binding above is remembered per running server, so a client that reconnects, restarts, or replays a saved list of ids has nothing recorded and every id takes the slower whole-tree path — where, on a label store, it is likely to be refused as ambiguous. Passing the source mailbox explicitly is the reliable way to stay scoped, and it overrides the remembered location. These parameters name where the ids came from; for batch-move-messages that is distinct from mailbox, the destination.

sourceMailbox and sourceAccount are an atomic scope pair: provide both for numeric ids. The server never fills in a missing account from mutable default-send state, because the same mailbox name can exist in more than one account and numeric ids are only unique within an account and mailbox. A whitespace-only source field is rejected. sourceAccount by itself pins nothing, since the mailbox is what an id is scoped to; imap:… ids ignore both fields because they carry their own account, mailbox, and UID identity.

A repeated id is one message. ids is treated as a set: a duplicate names the same message, so it is operated on once, and the batch returns one result per distinct id. success is therefore a count of messages, not of list positions.

batch-delete-messages

structuredContent carries countDelta — what the batch actually did to each source mailbox. See Auditing destructive operations.

⚠️ Safety: Destructive. Requires explicit user confirmation; search/list first to confirm the message ids.

batch-move-messages

structuredContent carries countDelta — what the batch actually did to each source mailbox. See Auditing destructive operations.

batch-mark-as-read / batch-mark-as-unread

batch-flag-messages / batch-unflag-messages

Mailbox Operations

list-mailboxes

List all mailboxes for an account.

Returns: List of mailbox paths (account-relative, e.g. Archive/Inbox for a nested mailbox — a top-level Inbox stays Inbox) with message and unread counts. A source that could not be read is named (partial: true + failedAccounts) rather than dropped, and a listing Mail refused outright returns an error naming the accounts that do exist — never an empty list.

Nested mailboxes and Gmail labels. Every mailbox parameter across this server (search-messages, list-messages, get-unread-count, move-message, delete-mailbox, rename-mailbox, create-rule's moveTo) accepts either the full path or a leaf name that is unique across the account — the same rule move-message has always used. A leaf name that matches more than one mailbox (e.g. a top-level Inbox and an Archive/Inbox on an Exchange account) is refused rather than guessed; pass the full path to disambiguate. This also means Gmail's nested special mailboxes now report their real path, e.g. [Gmail]/All Mail rather than All Mail — a visible change from before 2.17.0.

Matching ignores letter case and Unicode normalization form: a typed precomposed México (NFC) finds a mailbox the server stores decomposed (NFD — common for folders created on a Mac, and what iCloud keeps), and the server's own stored spelling is what gets selected. Two mailboxes whose names differ only in case or normalization look identical in any listing, so a name that matches both is refused with an error saying so — rename one of them. For the same reason create-mailbox treats a normalization-equivalent existing name as already existing, and rename-mailbox refuses to create such a twin.

Messages awaiting expunge are not listed. On IMAP accounts, search, list, thread and mail-stats queries only match messages not flagged \Deleted (IMAP UNDELETED). iCloud keeps flagged-but-never-expunged messages out of its message counts yet still returns them from UID SEARCH, which made a filter-less list-messages fail on such a mailbox before 2.19.16.

Very large IMAP mailboxes are read newest-first in bounded windows (#256). Above 10,000 messages, a filter-less list-messages/search-messages pages by message sequence number: page offset of limit is sequence numbers N-offset-limit+1 .. N-offset, so it fetches UIDs and flags for that range alone (plus a small margin; \Deleted ones are skipped and the page topped up from below) and full rows for the page. The cost is the page, not the offset: limit: 1 at offset 790,000 of a 793,614-message mailbox is one ~33-message FETCH, not a whole-mailbox SEARCH or a walk over every skipped message. Offsets count sequence positions. iCloud keeps messages awaiting expunge out of the sequence space, so there they are exact; on a server that keeps them in it, a page shifts by the number of such messages above it (they are never returned). A filtered search there runs the same criteria over newest-first sequence windows (5,000 messages, growing to 50,000) and stops once the page is full; the reported total then reads at least N unless the walk reached the bottom of the mailbox. A filtered search's deep offset has no such shortcut — which messages match is only known by searching the skipped windows — so its cost still grows with the offset (in 50,000-message SEARCH windows); narrow it with dateTo instead. A SEARCH or FETCH that fails names the mailbox, its size and the server's own reason (or a likely timeout) instead of reporting "no messages".

Mail's local "On My Mac" mailboxes are not children of any account — they hang off the application — so they are reported under the synthetic account label On My Mac. An unscoped call includes them (listed last); account="On My Mac" lists only them. on my computer, local and local folders are accepted as aliases.

They deliberately do not appear in list-accounts, which reports real accounts only: the local store is a store, not an account. Nothing selects it implicitly — omitting account still resolves to a real account for every other tool.

The mail inside them is reachable too: list-messages and search-messages accept account="On My Mac", and get-message resolves an id that lives only in a local mailbox. An id present both in an account mailbox and locally is reported as ambiguous rather than silently resolving to the account copy.

get-unread-count

Get unread message count.

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.

create-mailbox

Create a new mailbox.

delete-mailbox

Delete a mailbox.

⚠️ Safety: Destructive — deletes the mailbox and its contents. Requires explicit user confirmation; list mailboxes first to confirm the name.

rename-mailbox

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.

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.

list-smart-mailboxes

List existing smart mailboxes.

Parameters: None

Returns: List of smart mailbox names + criteria summary.

create-smart-mailbox

Create a smart mailbox with a simple contains rule.

Provide at least one of the three *Contains fields.

⚠️ Safety: edits SyncedSmartMailboxes.plist (backed up + atomic, existing smart mailboxes preserved). Quit Mail first for reliable results; the new smart mailbox appears the next time Mail launches.

delete-smart-mailbox

Delete a smart mailbox by name.

⚠️ Safety: destructive — removes the smart mailbox from SyncedSmartMailboxes.plist (backed up + atomic; every other smart mailbox is preserved). Not undoable in-app. Confirm the exact name with list-smart-mailboxes first, and quit Mail first for reliable results.

create-newsletter-smart-mailboxes

High-level tool: scan recent messages in your INBOXes, detect likely newsletters (volume + signals like List-Unsubscribe, noreply, repetitive subjects), and create smart mailboxes for them (names prefixed "NL: ...").

Defaults to a safe dry run that only proposes. Pass dryRun: false to actually create the smart mailboxes for newsletters cluttering your Inbox.

⚠️ Safety: with dryRun: false this edits SyncedSmartMailboxes.plist (backed up + atomic, existing entries preserved) and can create many smart mailboxes at once — review a dry run first. Scans up to ~400 recent messages per inbox via AppleScript, which can be slow on large mailboxes.

Account Operations

list-accounts

List all configured Mail accounts.

Parameters: None

Returns: List of account names and email addresses.

Rules

list-rules

List all mail rules.

Parameters: None

Returns: List of rule names and enabled status.

enable-rule / disable-rule

Enable or disable a mail rule.

create-rule

Create a Mail rule with one or more conditions and actions.

Each condition is { field, operator, value } where field is one of from, to, cc, subject, content and operator is one of contains, notContains, equals, beginsWith, endsWith. Actions: markRead / markFlagged / delete (booleans), moveTo (mailbox name) with optional moveToAccount.

New rules are created disabled by default, including rules that delete or move messages. Review the conditions and actions with list-rules and in Mail.app, then call enable-rule explicitly when the rule is approved. Set enabled: true only when immediate activation is deliberate.

Example:

{
  "name": "Newsletters",
  "conditions": [{ "field": "from", "operator": "contains", "value": "newsletter" }],
  "actions": { "markRead": true, "moveTo": "Reading" }
}

delete-rule

Delete a mail rule by name.

⚠️ Safety: Destructive. Requires explicit user confirmation; list rules first to confirm the name.

Contacts

search-contacts

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). Without either, the tool returns an empty list rather than an error.

Returns: List of contacts with name, email addresses, and phone numbers. Results are not truncated — a broad query returns every match.

Templates

Email templates are persisted to disk so they survive server restarts, stored as JSON at APPLE_MAIL_MCP_TEMPLATES_FILE (default ~/Library/Application Support/apple-mail-mcp/templates.json).

save-template

Save or update an email template.

list-templates

List all saved templates.

Parameters: None

get-template

Get a template by ID.

delete-template

Delete a template.

⚠️ Safety: Destructive — removes the template from the on-disk store. Requires explicit user confirmation; list templates first to confirm the id.

use-template

Create a draft from a template, with optional overrides.

Diagnostics

health-check

Verify Mail.app connectivity and permissions.

Parameters: None

Returns: Status of all health checks (app running, permissions, account access).

doctor

Run a full setup diagnostic: Mail.app automation permission, account state (flagging disabled accounts), and each configured IMAP/SMTP backend — each reported as ok / warn / fail with an actionable message.

Parameters: None

Returns: A per-check report (structuredContent carries the raw {healthy, checks[]}).

get-mail-stats

Get mail statistics.

Returns: Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d). The scoped IMAP path also returns a perMailbox breakdown.

Gathering stats costs one IMAP STATUS per mailbox, and Gmail lists every label as a mailbox, so a large account is not instant. Accounts are counted concurrently, and each is bounded by APPLE_MAIL_MCP_STATS_BUDGET_MS (default 25000). In the merged all-accounts path an account that fails or overruns is reported via partial: true + failedAccounts rather than being folded in as a silent zero; a scoped call to a single account returns an error naming the budget instead. Raise the budget if you have a very large account.

The whole call is additionally bounded by one wall-clock deadline, APPLE_MAIL_MCP_STATS_DEADLINE_MS (default 50000), which covers the Mail.app account enumeration as well as every per-account read. Per-step budgets alone were not enough: their worst cases add up, and the sum could exceed a client's request timeout, so the call died with nothing returned instead of degrading. Keep the deadline below your MCP client's request timeout — whatever cannot be read inside it is named in failedAccounts, so you always get a partial answer rather than a dead call.

Concurrent get-mail-stats calls do not run concurrently. Tool calls are serialized so they cannot race into Mail.app's single-threaded AppleScript dispatch, so each call waits for the ones ahead of it and per-call latency grows with queue depth — N concurrent calls take about N × the single-call cost. Since this is the most expensive read tool, that is very visible here: measured on 3 IMAP accounts, three concurrent calls returned at 5.5s / 10.3s / 15.6s against a ~5.2s solo cost. The deadline is measured from when the request arrived, so that wait is spent from the same budget as the work: a call that waited ≥1s reports queueWaitMs, and one that arrives with its deadline already spent returns straight away naming the queue rather than starting work whose answer would land after your client has given up. Issue these calls one at a time, and prefer get-unread-count when a single number will do.

get-sync-status

Check Mail.app sync activity.

Parameters: None

Returns: Whether sync is detected, pending uploads, recent activity, and seconds since last change.

Auditing destructive operations

delete-message, move-message, batch-delete-messages and batch-move-messages report what they actually did, not merely that Mail.app did not raise an error. This exists because of #155: a batch delete was reported to have removed two messages whose ids were never passed, and nothing in the server recorded enough to explain it.

countDelta — always on, no configuration

Every one of those four tools counts the affected source mailbox immediately before and immediately after the mutation, inside the same AppleScript it was already running (no extra osascript invocations, no measurable cost), and returns the comparison in structuredContent:

{
  "ok": true,
  "success": 2,
  "failed": 0,
  "countDelta": [
    {
      "account": "you@gmail.com",
      "mailbox": "INBOX",
      "before": 412,
      "after": 408,
      "expected": 2,
      "observed": 4,
      "status": "over"
    }
  ]
}

status is deliberately not a pass/fail flag:

unknownReason distinguishes four cases that are not interchangeable:

under was removed in 2.11.0. It used to mean "fewer left than expected" and was documented as routine. Field evidence retired it — see Why observed is a lower bound.

What an over warning does and does not tell you

Only over produces a warning in the tool's text response. Be precise about what that warning proves, because a warning is useful only for as long as it is trusted:

• It establishes that more messages left the source mailbox across the window of the operation than the operation accounted for. That is the data-loss direction, and it is the #155 signature.

• It does not establish that this server removed them. The reading is a before/after pair around a window, so anything else that removes mail from that mailbox inside the window reads identically: a Mail.app rule firing mid-batch, a server-side filter, another client (phone, webmail, a second Mail.app) deleting or moving, or an IMAP expunge landing between the two counts.

Concurrent departure is the benign cause to rule out first, and the warning text says so. What the asymmetry argument actually buys is the other half: concurrent arrivals cannot produce over, because a message arriving mid-operation raises the after-count and biases the reading short. That is why over is the interesting direction — a strong signal, not a proof.

Setting APPLE_MAIL_MCP_AUDIT_LOG is what settles which one you have: the collateral diff below names the messages that disappeared, and "the newsletter my rule files every morning" is a very different report from a message nothing should have touched.

Why observed is a lower bound (#155)

observed is the movement of Mail's count. It is a lower bound on how many messages left, not a count of how many left.

On iCloud, @scottstern0325 ran the check that settled this: for two batches reporting observed: 0, the messages were located in Trash, matched by date received + sender against the audit log's pre-image. The deletes had happened. Mail's count had not caught up. Across four readings — 0 of 4, 0 of 1 (a single-id delete), 15 of 16, and 14 of 15 — the shortfall bore no relation to batch size, which is what a lagging count looks like and not what a store-behaviour rule looks like.

So a short reading is not evidence about your operation. The per-id outcomes are what report success; this number is not. Do not retry on the strength of it — that is how a message gets deleted twice.

Two things follow:

• A count that does not move at all is still the ordinary reading on a store that flags deletions instead of removing them (Gmail label mailboxes, IMAP accounts with "move deleted messages to Trash" off). It reports unknownReason: "count-did-not-move" and says so, and it is never warned about — a warning that fires on every ordinary Gmail delete would be ignored exactly when it matters.

• To confirm where messages went, match them at the destination by date received plus sender — not by the numeric ids you passed. Ids are renumbered by the move and do not survive it.

Removed in 2.11.0: the "reported success with no observed effect" warning. Shipped in 2.10.30, it fired when the count was flat, the snapshot read cleanly and nothing had disappeared. Its premise was that the snapshot corroborated the count — but both are read back-to-back in the same script, and the record that prompted it turns out to have had both instruments stale at once. It therefore fired on stores that had done exactly what they were asked. It is gone rather than narrowed; over is the only surviving assertion.

Three more honesty rules:

• The expectation is per source mailbox. On a Gmail label store, deleting the INBOX copy drops the \Inbox label and deleting the [Gmail]/All Mail copy trashes the message — different operations, but either way the mailbox the ids came from loses exactly one entry per id. That is what is compared. A move's destination count is not checked.

• A move whose destination is the source mailbox is not compared at all. No message should leave, but what Mail does to the count when a message is re-filed into the mailbox it already occupies is unspecified — so expected is null, status is unknown, note says why, and no warning is raised. A warning computed against a guessed expectation would fire on an operation that did exactly what it was asked to, which is the one thing this instrumentation must never do.

  This makes a self-move a blind spot for the always-on layer, and the cost is worth stating plainly: if messages genuinely do disappear during a self-move, nothing warns you, because there was no expectation to compare against. status is unknown rather than match, so the result does not claim the operation was clean — but it does not flag it either. The collateral diff still names anything that vanished, so enable APPLE_MAIL_MCP_AUDIT_LOG if you need coverage for same-mailbox moves.

• A repeated id is one message. The batch tools operate on each distinct id once and return one result per distinct id, so success counts messages rather than list positions — and expected stays comparable with the mailbox instead of double-counting a duplicate into a false over.

imap: ids are reconciled too, as of 2.15.0. batch-delete-messages and batch-move-messages return the same countDelta structure on the IMAP path, so one shape covers both backends and a mixed batch reports an entry per source mailbox from whichever backend handled it. The entries are concatenated, never summed — Mail's own count can lag (#155) while the server's STATUS cannot, and averaging the two would hide which reading you were looking at.

Only the operations that actually remove messages from their source reconcile. batch-mark-as-read and the flag tools change no count, so emitting expected: N, observed: 0 for them would manufacture an alarm; they report no countDelta at all.

Note the mis-targeting class countDelta was originally built for cannot occur on the IMAP path — a UID names exactly one message in exactly one mailbox — so there the value is effect confirmation rather than target confirmation.

Single-message tools carry a post-condition check instead. delete-message and move-message on an imap: id return a verification object in structuredContent:

{
  "verification": {
    "verdict": "verified",
    "how": "COPYUID: UID 5 arrived in \"Archive\" as UID 91"
  }
}

unverified is not a failure and must not be rendered as one — it means "accepted, no observation either way". It is reported rather than hidden because an absent verification must never read as a successful one, the same rule the collateral diff follows. A message that is still in the source mailbox after an accepted move is reported unverified rather than failed, because a Gmail label store can legitimately keep a message visible in an all-mail view after a move.

APPLE_MAIL_MCP_AUDIT_LOG — opt-in forensic log

When set, each destructive operation appends one JSON object per line containing: timestamp, tool name, server version, the arguments it was called with, the pre-image of every message it resolved (account, mailbox, numeric id, RFC Message-ID, date received), the per-id outcome (ok / notfound / error + reason), the countDelta above, and the collateral diff.

The pre-image is the part that matters after the fact: a Mail.app numeric id is unique only within a mailbox and is reused, so on its own it proves nothing about which message was acted on. The RFC Message-ID does.

The record is framed against its own contents. The Message-ID and (when enabled) the subject are written by whoever sent the mail, so the control characters this server frames records with are stripped out of every such value before it is written — a Message-ID crafted to close a record and open a forged one cannot invent evidence in the log it is being recorded in. The same stripping is applied to every other value read out of Mail at runtime (date received, mailbox and account names, the text of an error Mail raised, the candidate list behind an "ambiguous id" refusal), so no emitter is an exception. A value that arrives with those characters in it (which a well-formed Message-ID never does) is logged with each of them replaced by U+FFFD, so the record shows that the value was altered rather than quietly shortening it.

Collateral identification — which messages actually disappeared

Also gated on APPLE_MAIL_MCP_AUDIT_LOG. The mailbox's (numeric id, Message-ID) pairs are captured before and after the mutation and diffed, so the log names every message that left — including ones the caller never listed:

{
  "account": "you@gmail.com",
  "mailbox": "INBOX",
  "snapshot": "ok",
  "disappeared": [
    { "id": "75811", "messageId": "a@example.com" },
    { "id": "75814", "messageId": "d@example.com" }
  ],
  "unrequested": [{ "id": "75814", "messageId": "d@example.com" }],
  "appeared": []
}

A non-empty unrequested is the #155 symptom, with names attached. Please attach that line to the issue if you ever see one.

id is always the plain decimal id you passed, even on a mailbox whose ids exceed AppleScript's 2^29 integer range (where Mail hands them back as 9.99999999E+8). That normalisation is also what keeps unrequested truthful: compared in the raw form, a message you explicitly asked to delete would be reported here as collateral.

This is O(mailbox size), so it is bounded by APPLE_MAIL_MCP_AUDIT_SNAPSHOT_MAX. When the bound bites, the record says so explicitly ("snapshot": "skipped" with a reason) rather than omitting the field — a silently skipped snapshot would read as "nothing collateral happened", which is worse than no snapshot at all. countDelta is unaffected by the skip and still reconciles the counts.

Partial snapshots on large mailboxes

The mailbox is read in APPLE_MAIL_MCP_AUDIT_SNAPSHOT_CHUNK-sized slices, each retried once on its own. It used to be a single whole-mailbox read, which meant Mail declining that one request lost the entire diff — and the bigger the mailbox, the more likely that was. The mechanism that attributes collateral damage was therefore least reliable exactly when the blast radius was largest.

When a slice still will not read, the snapshot is reported as partial and it names its own gap:

{
  "snapshot": "partial",
  "unobserved": [{ "phase": "after", "ranges": "251-500" }],
  "appeared": [],
  "skipReason": "Mail would not read 251-500 (after) of this mailbox, so the snapshot has a hole in it. …"
}

Each half of the diff is withheld when the snapshot that could refute it has a hole, because a wrong name here is worse than a missing one:

An absent field means "not computable", never "empty". Check "snapshot": "ok" before reading disappeared as a clean bill of health.

⚠️ "ok" is necessary, not sufficient. The enumeration's range is bounded by Mail's own message count, and #155 established that count can lag the mutation. A count reading low truncates the enumeration silently — the unread tail is never requested, so it never registers as a failed slice and the status still says "ok" — and messages past that bound would then look like they disappeared. Until that is fixed, treat a disappeared entry as a lead to check, not a proof.

Privacy, and what the file costs you

• Default: identifying metadata only — Message-ID, date, mailbox, account, numeric id. Enough to say which message, nothing about what it says.

• Subjects are behind their own opt-in (APPLE_MAIL_MCP_AUDIT_SUBJECTS=1) because a subject line is frequently the entire sensitive payload, and it is not needed to diagnose #155.

• Message bodies are never logged, under any setting.

• The file grows without bound and is never rotated or truncated by this server. Point it somewhere you control, and delete it when you are done. It is written with your user's permissions, wherever you point it; there is no default location precisely so that turning it on is a deliberate act.

• Writes go to that file and nowhere else. Diagnostics go to stderr; nothing is ever written to stdout, which is the JSON-RPC transport.

Usage Patterns

Basic Workflow

User: "Check my inbox for new emails"
AI: [calls list-messages]
    "You have 12 messages. Here are the most recent..."

User: "Show me emails from Sarah"
AI: [calls search-messages with query="Sarah"]
    "Found 3 emails from Sarah across all mailboxes..."

User: "Read the first one"
AI: [calls get-message with id="..."]
    "Subject: Project Update..."

Working with Accounts

By default, operations use Mail.app's configured default send account. Search operations check all accounts when no account is specified. To work with specific accounts:

User: "What email accounts do I have?"
AI: [calls list-accounts]
    "You have 3 accounts: iCloud, Gmail, Work Exchange"

User: "Show unread emails in my Work account"
AI: [calls list-messages with account="Work Exchange", mailbox="INBOX"]
    "Your Work account has 5 unread messages..."

To pin which account is used when a tool call omits account, set the APPLE_MAIL_MCP_DEFAULT_ACCOUNT environment variable to an account name or email. When unset (the default), the server falls back to Mail.app's default-send account if it is enabled, otherwise the first enabled account. A disabled account is never selected implicitly — this env var (an explicit, deliberate pin) is one of the few ways to target one (#47).

Sending Emails Safely

User: "Draft an email to the team about the deadline"
AI: [calls create-draft with to=["team@..."], subject="...", body="..."]
    "I've created a draft. Please review it in Mail.app before sending."

User: "Send it"
AI: [User opens Mail.app and sends manually, or AI calls send-email]

Sending Personalized Emails (Mail Merge)

User: "Send a personalized email to Alice (alice@acme.com), Bob (bob@globex.com),
       and Carol (carol@initech.com). Subject: 'Project Update for {{Company}}',
       Body: 'Hi {{Name}}, here is the latest update for {{Company}}.'"
AI: [calls send-serial-email with recipients, subject template, and body template]
    "Successfully sent 3 email(s):
      - alice@acme.com: sent
      - bob@globex.com: sent
      - carol@initech.com: sent"

Organizing Messages

User: "Move all newsletters to Archive"
AI: [calls search-messages to find newsletters]
AI: [calls move-message for each, with mailbox="Archive"]
    "Moved 8 newsletters to Archive"

Documentation

• Threat model

• IMAP / SMTP setup guide

• Node runtime and TCC permissions

• Stability and performance audit

Installation Options

npm (Recommended)

npm install -g apple-mail-mcp

From Source

git clone https://github.com/sweetrb/apple-mail-mcp.git
cd apple-mail-mcp

The repo ships prebuilt, dependency-free build/index.js and build/cli.js bundles, so a bare clone runs with nothing but Node installed. npm install and npm run build are only needed when you change the source.

You can also install straight from GitHub with npm install -g github:sweetrb/apple-mail-mcp, but that builds from source (requires pnpm) — prefer the registry package above.

If installed from source, use this configuration:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/apple-mail-mcp/build/index.js"]
    }
  }
}

Running from a clone in Claude Code (project-scope .mcp.json)

This repo ships a .mcp.json at its root so that, when you run claude from inside a clone, the server is registered automatically as a project-scope server — no manual config needed. Just launch Claude Code from the repo directory and approve the server when prompted (the bundled build/index.js is committed, so no build step is required).

The entrypoint is written as:

"args": ["${CLAUDE_PROJECT_DIR:-.}/build/index.js"]

CLAUDE_PROJECT_DIR is the variable Claude Code injects into a project/user-scoped server's environment, and it resolves to the repo root. You must launch claude from inside the repo for this to work — the bare . fallback is only a last resort and is not reliable, because it resolves against the launching process's working directory, not the repo.

Why not ${CLAUDE_PLUGIN_ROOT}? CLAUDE_PLUGIN_ROOT is set only for marketplace plugin installs, never for a project-scope clone, so it can't drive the clone workflow. Conversely, a plugin install can't use CLAUDE_PROJECT_DIR (in a plugin, that points at the user's project, not the plugin's own directory). Claude Code does not support nested defaults like ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}, so a single entrypoint string cannot serve both contexts. The two distribution paths are therefore decoupled: the plugin carries its own MCP config in .claude-plugin/plugin.json (using ${CLAUDE_PLUGIN_ROOT}), while the root .mcp.json is dedicated to the clone workflow (using ${CLAUDE_PROJECT_DIR:-.}). Because plugin.json declares its own mcpServers, the plugin does not also auto-load the root .mcp.json, so there is no double-registration.

Heads-up on scope precedence: project-scope (.mcp.json) outranks user-scope. If you also have an apple-mail entry registered at user scope (e.g. an absolute path in ~/.claude.json), the project-scope entry wins and the user-scope one is ignored entirely. Pick one — for local development on this repo, the project-scope .mcp.json is the intended source. To pin a specific local build instead, register it at local scope (claude mcp add apple-mail -s local -- node /abs/path/build/index.js), which outranks project scope.

Security and Privacy

• 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.

• Attachment read boundary - Outbound file attachments may come from ordinary files under the home directory, /Volumes, or temporary directories by default. Hidden files and known credential/configuration locations (including .ssh, .aws, .config/gh, Keychains, and application config.json files) are denied. Set APPLE_MAIL_MCP_ATTACHMENT_READ_ROOTS to a colon-separated list of explicit absolute additional roots when a deliberate other location is required. Paths are canonicalized before use, so symlink escapes are rejected. /tmp is world-writable and is a convenience root, not a user-content trust boundary. Inline base64 attachments are unaffected.

Known Limitations

Mail.app <blockquote> wrapping on macOS 15+ (workaround in v1.6.0)

On macOS 15+ Mail.app wraps AppleScript-injected message bodies in <blockquote type="cite"> under the Apple-Mail-URLShareWrapperClass template, so mail sent via the default applescript transport renders to recipients as quoted/forwarded content (Apple radar FB11734014, open since Ventura, no fix). Since v1.6.0, send-email accepts transport: "smtp" to bypass Mail.app and send clean MIME directly — see SMTP transport. The AppleScript path is still the default and still exhibits Apple's wrapping. (#12)

Reply / Forward from Background Processes (Fixed in v1.4.0)

Prior to v1.4.0, reply-to-message and forward-message would send messages with empty body text when the MCP server ran as a background process (e.g., spawned via execSync from Node.js, which is how Claude Code invokes it).

Root cause: The AppleScript reply msg with opening window command creates a GUI compose window asynchronously. When set content runs immediately after, the window may not be ready, and the content assignment is silently ignored. Delays (delay 1, delay 2) were unreliable — the compose window's readiness depends on system load, Mail.app state, and whether the process has GUI access.

Fix: Replaced with opening window with without opening window for both reply and forward commands. With this approach, set content works immediately and reliably from background processes. In-Reply-To and References headers are still set correctly by Mail.app, and no GUI compose window is opened.

Update (v2.5.0): when SMTP is configured, reply-to-message and forward-message now prefer clean direct SMTP instead of AppleScript — the same prefer-direct model as send-email. Replies are threaded with RFC 5322 In-Reply-To/References headers built from the original message; forwards start a new conversation. With transport omitted, the AppleScript without opening window path above is used only when SMTP is not configured or a draft is requested. Since v2.17.8, a selected SMTP path returns source/configuration/threading errors instead of silently falling back; explicit transport: "applescript" remains available.

See #7 for full details and the list of approaches that were tested.

Backslash Escaping (Important for AI Agents)

When sending content containing backslashes (\) to this MCP server, you must escape them as \\ in the JSON parameters.

Why: The MCP protocol uses JSON for parameter passing. In JSON, a single backslash is an escape character. To include a literal backslash in content, it must be escaped as \\.

Correct — email containing a shell path with an escaped space:

{
  "to": ["colleague@company.com"],
  "subject": "File Location",
  "body": "Run: cp ~/Library/Mobile\\ Documents/report.pdf ~/Desktop/"
}

→ arrives as: Run: cp ~/Library/Mobile\ Documents/report.pdf ~/Desktop/

In a JSON string literal, \\ — two characters — denotes one literal backslash. Four backslashes (\\\\) denote two literal backslashes, so send those only when the text genuinely contains \\.

Incorrect — the unescaped backslash makes this invalid JSON:

"body": "Run: cp ~/Library/Mobile\ Documents/report.pdf ~/Desktop/"

\ (backslash-space) is not a valid JSON escape sequence, so the call is rejected — or, with a laxer parser, the backslash is silently dropped.

Common patterns requiring escaping:

• Shell escaped spaces: Mobile\ Documents → Mobile\\ Documents in JSON

• Regex patterns: \d+ → \\d+ in JSON

• A literal double backslash: \\ → \\\\ in JSON

If you see errors when sending emails with backslashes, double-check that backslashes are properly escaped in the JSON payload.

Troubleshooting

"Mail.app not responding"

• Ensure Mail.app is not frozen

• Try opening Mail.app manually

• Restart the MCP server

"Permission denied"

• macOS needs automation permission

• Go to System Settings > Privacy & Security > Automation

• Ensure your terminal/Claude has permission to control Mail

• On a Mac that isn't set to US English, macOS words this refusal in the system language — Not authorised to send Apple events to Mail. (-1743) on en-GB/en-AU/en-IE, and fully translated on fr/de/es. Before v2.17.10 the server didn't recognise those spellings, so health-check/doctor reported permissions: ok and then blamed missing accounts ("No Mail accounts found. Set up an account in Mail.app first."). If you see that on a Mac whose Mail accounts are already configured, upgrade and re-run doctor.

"Message not found"

• Message may have been deleted or moved

• Message IDs change if the message is moved between mailboxes

• Use search-messages to find the current message ID

• "not found in the mailboxes scanned" with a list of mailboxes means the numeric-id scan skipped those because they hold more than APPLE_MAIL_MAX_BYID_SCAN_MAILBOX messages (default 50000). The message may be in one of them: pass account + mailbox to read it from there, or use its imap: id (#270).

• "stopped … before reaching: …" lists the mailboxes the scan never got to (its ~9s budget ran out, or a mailbox's size count timed out and Mail.app was left busy finishing it). A timed-out mailbox is remembered for 7 days and skipped from then on, so retrying shortly usually covers the rest. "Mail.app did not answer within 3s" means Mail.app was still busy with such a count when the lookup started — retry in a little while.

• "Mail.app is not running" — numeric-id reads need Mail.app open; the server never launches it for them. imap: ids read over IMAP without Mail.app.

"... is present in more than one mailbox"

• A bare numeric ID identifies a message only within a mailbox, and a label store (Gmail, iCloud) reports the same message under the same ID in INBOX, Important and All Mail at once. The server refuses rather than guessing which copy you meant.

• Fix it by running list-messages/search-messages on the mailbox you actually want to act on, then using the IDs from that result — the operation is then scoped to that mailbox.

• It only affects IDs the server hasn't seen listed (carried over from an earlier session, or typed by hand). imap:… IDs encode their own mailbox and never hit this.

search-messages says "Partial results" or skips a mailbox

• This is expected for very large IMAP/Gmail mailboxes (e.g. Gmail's All Mail, Important): Apple Mail can't scan them via AppleScript before timing out, so they're skipped and named in the result rather than silently returning empty.

• To search inside one, scope the call with mailbox and a dateFrom/dateTo window.

• Raise or disable the threshold with APPLE_MAIL_MAX_SEARCH_MAILBOX (default 5000; 0 disables the guard) — note that disabling it can make a single search take minutes.

• A Partial results warning means coverage was incomplete; it is not a confirmed "no such mail."

"Account not found"

• Account names must match exactly (case-sensitive)

• Use list-accounts to see exact account names

"Failed to send email"

• Check your network connection

• Verify Mail.app can send emails manually

• Check if the account is configured correctly in Mail.app

"invalid outputSchema … unsupported dialect" — every tool is refused

• Full text: Tool '<name>' has an invalid outputSchema: JSON Schema declares an unsupported dialect ("$schema": "http://json-schema.org/draft-07/schema#"). The default validator supports JSON Schema 2020-12 only. The server connects, but no tool is usable.

• Upgrade to 2.10.12 or later. Earlier versions advertised their tool schemas in JSON Schema draft-07 (the MCP SDK's converter default); MCP has since standardized on 2020-12 and clients reject anything else. 2.10.12 normalizes every advertised inputSchema/outputSchema to 2020-12 on the way out. See issue #147.

• Nothing to configure — restart your host app after upgrading so it re-reads the tool list.

apple-mail server fails to connect when run from a clone

• The root .mcp.json resolves its entrypoint via ${CLAUDE_PROJECT_DIR:-.}/build/index.js. Launch claude from inside the repo directory — CLAUDE_PROJECT_DIR only resolves to the repo root in that case; the bare . fallback uses the launching shell's working directory and will point at the wrong place otherwise.

• If you've been editing the source, rerun npm run build — the server is build/index.js, and the committed bundle only reflects your changes after a rebuild.

• Run claude mcp list to check status. If you see a conflicting scopes warning for apple-mail, you have it registered at more than one scope; project-scope wins. See Running from a clone for how scope precedence resolves.

• If claude mcp get apple-mail shows ⏸ Pending approval, approve the project-scope server (Claude Code prompts on startup, or run it again after approving).

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.

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

Author

Rob Sweet - President, Superior Technologies Research

A software consulting, contracting, and development company.

• Email: rob@superiortech.io

• GitHub: @sweetrb

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Related Projects

Part of a family of macOS MCP servers:

• apple-notes-mcp — MCP server for Apple Notes (create, search, update, and export notes)

• apple-numbers-mcp — MCP server for Apple Numbers (read and write .numbers spreadsheets)

• apple-photos-mcp — MCP server for Apple Photos (query metadata and export originals)

Recurring macOS permission prompts

If macOS keeps re-prompting for Full Disk Access or Automation for node (often after a brew upgrade), see docs/NODE-RUNTIME-AND-TCC-PERMISSIONS.md — the fix is to run this server under the official, Developer-ID-signed Node so the grant survives Node updates.