che-apple-mail-mcp

The most comprehensive Apple Mail MCP server - 54 tools with SQLite-powered millisecond search across 250K+ emails.

English | 繁體中文

---

Why che-apple-mail-mcp?

| Feature | Other MCPs | che-apple-mail-mcp | |---------|------------|-------------------| | Total Tools | ~20 | 54 | | Language | Python | Swift (Native) | | Search Speed | Seconds (AppleScript) | Milliseconds (SQLite) | | Search Fields | Subject/Sender | Subject/Sender/Recipient/Date | | Batch Operations | No | Up to 50 emails per call | | Mailbox Management | Basic | Full CRUD | | Email Colors | No | 7 flag colors + background | | VIP Management | No | Yes | | Rule Management | Partial | Full CRUD | | Signatures | No | Yes | | Raw Headers/Source | No | Yes |

---

Quick Start

Install the plugin. It brings the signed binary, the /archive-mail command family, the safety rules, and the staleness hook as one unit:

claude plugin marketplace add PsychQuant/che-apple-mail-mcp
claude plugin install che-apple-mail-mcp@che-apple-mail-mcp

Then grant permissions — the setup window shows live status and links straight to the right System Settings pane:

~/bin/CheAppleMailMCP --setup

💡 Full Disk Access is what makes the fast SQLite read path and batch_export_emails_markdown work. Without it the tools still run but read little or nothing, which is easy to mistake for a bug rather than a permission. macOS does not let an app request FDA programmatically — it has to be ticked by hand — which is exactly what the setup window is there to make quick.

Plugin vs MCP-only

Registering the MCP server by itself is a supported advanced path, but it is a strictly smaller install. Choose it knowingly — nothing at runtime will tell you these are missing (#353):

| Shipped by the plugin | Present with MCP-only | |---|---| | All 54 MCP tools | ✅ yes | | /archive-mail + -migrate / -rebuild-threads / -repair-synthetic-ids / -view | ❌ the archiving SOP does not exist | | rules/compose-wrapper-free.md — what the cite-block was, and what a refused compose call means | ⚠️ background: since #304 the wrapper is structurally impossible, so this rule now explains the six refusal reasons and their recipes rather than guarding against a silent fallback | | rules/confirmation-triggers.md, rules/false-positive-detection.md | ❌ no confirmation discipline on destructive operations | | hooks/session-start.sh — staleness kill | ❌ a session can keep running a stale binary after an upgrade | | Developer ID signed + notarized binary | ❌ a self-built binary is ad-hoc signed; on macOS 26 TCC cannot reliably hold FDA/Automation for it, so permissions appear to be granted and then stop working (#211) | | Version sidecar → --self-update + the #303 staleness self-check | ❌ no sidecar next to a hand-built binary, so that check is permanently silent |

<details> <summary><strong>Advanced: register the MCP server only</strong> (development, or you want no plugin)</summary>

git clone https://github.com/PsychQuant/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

# --scope user     : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --               : separator between claude options and the command
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Install the binary to a local directory like ~/bin/. Avoid cloud-synced folders (Dropbox, iCloud, OneDrive) — sync activity causes MCP connection timeouts.

For a self-built binary to hold TCC permissions across rebuilds, sign it with a Developer ID; see Signing & Notarization. Otherwise expect to re-grant permissions after every build.

</details>

---

Recent Releases

For full details see CHANGELOG.md.

v2.7.2 (2026-05-10) — attachmentFragment cluster + fallback parity

• Hardened attachmentFragment indent across all 3 callers + removed dead MailController.attachmentScript helper that bypassed v2.7.0's race-mitigation delays (#61, #62)
• Attachment count cap (50) + env-configurable delays via CHE_MAIL_ATTACHMENT_DELAY_BETWEEN / _TRAILING (#63, #64)
• get_email_metadata SQLite path now falls back to AppleScript on error — last read-tool gap closed; all 8 SQLite-first read tools now have parity fallback (#71)

v2.7.1 (2026-05-09) — base64 fix + .partial.emlx + observability

• Critical: RFC822 header/body split was returning a relative array index instead of an absolute Data index, causing html_body to begin with "sion: 1.0\n\n<base64>" for some Android Gmail messages — raw base64 leaked into LLM context and triggered AUP false-positives downstream (#72)
• save_attachment now reads from Attachments/<rowId>/<part_id>/<filename> cache when .partial.emlx body is empty — no more silent 0-byte writes for IMAP messages with stripped binaries (#66)
• SQLite fast-path failures now log to stderr (SQLite ... fast path failed for rowId=...; falling through to AppleScript) (#69)

v2.7.0 (2026-05-04) — Mail.app race mitigation

• Multi-attachment AppleScript paced with 0.3s between + 0.5s trailing delays to mitigate Mail.app silently dropping attachments under fast IPC (#60)

v2.6.0 (2026-05-03) — Security & validation hardening (8 PRs, 16 issues)

• forward_email plain mode now embeds RFC 3676 > quoted original (parity with reply_email's #43 fix) (#44)
• Hard-fail on tool param type mismatch — bool / [String] no longer silently coerced (#35)
• Recipient email validation rejects header injection (control chars, missing/multiple @) (#41)
• cc_additional deduplicates case-insensitively (#34)
• Attachment path deny-list (~/.ssh, Keychains, TCC db, browser cookies) + symlink-resolved + new MAIL_MCP_ATTACHMENT_ROOTS env allow-list (#38)
• All 17 id-taking tools hard-validate id as Int at handler boundary — defeats AppleScript predicate injection (#50)
• Gated integration tests for reply_email runtime (#37, #45) + smoke matrix templates (#46, #47)

v2.5.0 (2026-04-17) — Composing format parameter

• All 4 composing tools (compose_email / create_draft / reply_email / forward_email) gain format: "plain" | "markdown" | "html" param (closes #14, #15)
• New message-composition capability spec

---

All 54 Tools

<details> <summary><b>Accounts (2)</b></summary>

| Tool | Description | |------|-------------| | list_accounts | List all mail accounts | | get_account_info | Get account details |

</details> <details> <summary><b>Mailboxes (4)</b></summary>

| Tool | Description | |------|-------------| | list_mailboxes | List all mailboxes (folders) | | create_mailbox | Create a new mailbox | | delete_mailbox | Delete a mailbox | | get_special_mailboxes | Get special mailbox names (inbox, drafts, sent, trash, junk, outbox) |

</details> <details> <summary><b>Emails (7)</b></summary>

| Tool | Description | |------|-------------| | list_emails | List emails in a mailbox | | get_email | Get full email content | | search_emails | Search by subject/content | | get_unread_count | Get unread count | | get_email_headers | Get all email headers | | get_email_source | Get raw email source | | get_email_metadata | Get metadata (forwarded, replied, size) |

</details> <details> <summary><b>Actions (8)</b></summary>

| Tool | Description | |------|-------------| | mark_read | Mark as read/unread | | flag_email | Flag/unflag email | | set_flag_color | Set flag color (7 colors) | | set_background_color | Set email background color | | mark_as_junk | Mark as junk/not junk | | move_email | Move to another mailbox | | copy_email | Copy to another mailbox | | delete_email | Delete email (to trash) |

</details> <details> <summary><b>Compose (5)</b></summary>

| Tool | Description | |------|-------------| | compose_email | Send new email (supports cc/bcc/attachments — bare addresses only: a display-name recipient in any list is refused on a send, use create_draft (#404); format: plain only since #304; optional from_address for multi-account sender selection — see #131, clean path supported via the verified From popup, #219). Bodies always come from Mail's own editor — see #175 / check_accessibility; a call that cannot run cleanly FAILS with a named reason and creates nothing (#304) | | reply_email | Reply to email. Optional: cc_additional, attachments, save_as_draft, format (since v2.4.0). Plain mode embeds RFC 3676 > quoted original (since v2.5.0 / #43). The new body is pasted into Mail's native reply (#218); a non-plain format or a missing Accessibility grant FAILS instead of falling back (#304) | | forward_email | Forward email. Optional body + format. Plain mode embeds RFC 3676 > quoted original (since v2.5.0+ / #44). A bodyless forward assigns nothing and needs no Accessibility grant; with a body, same rules as reply_email (#218 / #304) | | redirect_email | Redirect email (keeps original sender) | | open_mailto | Open mailto URL |

Reply-as-draft example (v2.4.0+)

Reply to a thread, add extra CC, attach files, and save as a draft for human review before sending:

reply_email(
    id="<message id from search_emails>",
    mailbox="INBOX",
    account_name="iCloud",
    body="Reply text"