Repository navigation
Releases
Apple Mail MCP v3.12.5
- Retry malformed outer MIME framing once before publishing an EML. Keep a
message pending if Mail still returns malformed source. - Save native iCalendar source as
.icsand preserve its optional Mail
property list separately. Checkpoints recognize the published calendar file. - Bundle the archive-export workflow with its verification, attachment
recovery, and local search scripts. Build a SQLite full-text index from a
verified archive manifest, with links back to the original files.
Apple Mail MCP v3.12.4
- Mailbox exports use smaller pages, publish complete files atomically, and
return confirmed paths and pending message IDs when a batch times out.
EML exports skip the rendered-body read on the explicit batch path. - Search and filtered selection paginate across accounts and mailboxes after
merging results. Mailbox inventory, attachment saves, and move and trash
operations report partial results and failed items. - Calendar writes stop when a requested conflict check is incomplete.
Recurring deletes preserve removal receipts if follow-up verification fails. - Installed plugin archives advertise their release version in the MCP
handshake, including when the runtime starts entirely offline.
Apple Mail MCP v3.12.3
Ships the EventKit calendar fast path in the offline plugin payload, with operator guidance for dependency and calendar authorization status. Adds the non-interactive apple-mail calendar-doctor command. Calendars full access remains a separate operator permission step.
Source: PR #107, AGENTIC-2982. Signed annotated tag v3.12.3 targets 3695be8b0f19e1f779e3078aa0bcbf4d51c196dc.
Verification: the complete source release gate passed on that exact main commit, including strict lint and typing, 2,778 collected tests, artifact and manifest parity, MCPB and Claude strict structure checks, and fresh offline installs from both ZIP and MCPB. The generated-wrapper check skipped because no mcporter wrapper was on PATH.
Downloadable ZIP, Cowork plugin, and MCPB are attached. Marketplace admission and client refresh are separate delivery stages.
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
Apple Mail MCP v3.12.1
Changes
- Calendar reads now recover stable opaque references when
calendarIdentifieris unavailable, carry those selectors through bounded reads and writes, and fail closed when an exact-name fallback is ambiguous. Calendar listings also expose source metadata when it is available. - Reply-state JSON now separates raw Mail metadata from verified Sent threading. It preserves
was_replied_to, addsmail_was_replied_to, nullablehas_sent_replyandreply_state, and reports the completeness and errors of the bounded Sent scan.
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.1.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.
v3.11.9
- Separate plugin hosts could automate Mail at the same time. The existing
single-flight lock applied only inside one Python process, so concurrent
Codex, Claude, or Cursor plugin servers could interleave AppleScript calls
with a native reply's focus-guarded typing transaction. Everyosascript
invocation now also acquires a version-independent advisory lock in a
private per-user cache directory. The lock releases when a process exits,
including after a crash, and fails closed if its directory or file cannot be
safely trusted.
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.11.9.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.