Skip to content

Apple Mail MCP v3.12.2

Choose a tag to compare

@agenticassets agenticassets released this 07 Sep 20:23
· 10 commits to main since this release
edc675c

Changes

Five root causes behind one reported symptom: a conversation with 10 accessible members across 4 mailboxes came back as 5, reporting itself complete. Nothing was lost inside a try, so no loss counter moved and the short result rendered under a clean banner.

  • get_email_thread no longer reports a truncated conversation as complete. The per-mailbox candidate scan was bounded by max_messages, which is the return limit, so asking for at most 50 members also examined only the newest 50 messages of each mailbox. The scan bound is now derived from the date window (base 120, plus 15 per recent_days day, capped at 400), with a new scan_messages parameter to override it. JSON adds thread_incomplete as the single flag to branch on, plus scan_ceiling_hit, scan_messages_applied, and per-item attachment_count (null when unreadable, which is not the same as 0). A caller's own recent_days cutoff and max_messages cap are reported separately as window_truncated / date_floor_hit and return_limit_reached, so a bound you chose yourself does not read as a defect.
  • mailbox="All" works. It returned Error: Mailbox not found: All for a documented argument, and now resolves the anchor's real mailbox through a bounded probe. An anchor the scan missed is appended with anchor_recovered: true rather than dropped from its own thread.
  • list_email_attachments can search beyond the inbox. It was inbox-only, and a message with no attachments was byte-identical to an id that was never found. It now takes mailbox / mailboxes and reports mailboxes_searched, resolved_message_ids, unresolved_message_ids, complete, and errors.
  • export_emails(scope="thread") stops printing an unqualified success banner over a partial export. Candidate mailboxes now come from the returned thread records rather than a hardcoded list, exported ids are reconciled against requested ids, and any shortfall prints as a PARTIAL: line.
  • search_emails sizes its scan from date_from. It previously sized the scan from the page (limit + offset + 1) and ignored date_from entirely, and its scan_ceiling_applied marker was compared against the wrong value so it never armed.

Raising the thread scan bound costs wall time. Measured live across three mailboxes with only the bound varied: 50 took 6.8s and found 5 members; 150 took 10.9s and found all 9; 400 cost no more than 150. None of this widens the 50-message search or inbox ceilings.

Install

Client Path
Claude Code claude plugin marketplace add Agentic-Assets/apple-mail-mcp then claude plugin install apple-mail@apple-mail-mcp
Claude Desktop (chat) Download apple-mail-mcp-v3.12.2.mcpb below, then Settings -> Extensions -> Install from file
Claude Desktop (Cowork) Download apple-mail.plugin below, then Customize -> Add plugin -> Upload plugin
Codex codex plugin marketplace add Agentic-Assets/apple-mail-mcp then codex plugin add apple-mail@apple-mail-mcp
Cursor Point Cursor at the Agentic-Assets/apple-mail-mcp marketplace and install apple-mail

macOS only. Requires Mail.app and Python 3.10+. The plugin launches with --draft-safe: it creates reviewable drafts and never sends mail on its own.

Full notes: CHANGELOG.md