Repository navigation
Apple Mail MCP v3.12.2
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_threadno longer reports a truncated conversation as complete. The per-mailbox candidate scan was bounded bymax_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 perrecent_daysday, capped at 400), with a newscan_messagesparameter to override it. JSON addsthread_incompleteas the single flag to branch on, plusscan_ceiling_hit,scan_messages_applied, and per-itemattachment_count(null when unreadable, which is not the same as 0). A caller's ownrecent_dayscutoff andmax_messagescap are reported separately aswindow_truncated/date_floor_hitandreturn_limit_reached, so a bound you chose yourself does not read as a defect.mailbox="All"works. It returnedError: Mailbox not found: Allfor a documented argument, and now resolves the anchor's real mailbox through a bounded probe. An anchor the scan missed is appended withanchor_recovered: truerather than dropped from its own thread.list_email_attachmentscan 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 takesmailbox/mailboxesand reportsmailboxes_searched,resolved_message_ids,unresolved_message_ids,complete, anderrors.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 aPARTIAL:line.search_emailssizes its scan fromdate_from. It previously sized the scan from the page (limit + offset + 1) and ignoreddate_fromentirely, and itsscan_ceiling_appliedmarker 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