apple-mail-mcp
Locally operate Apple Mail through MCP: search and read mail, handle threads and attachments, send/reply/draft/schedule, and perform reviewed bulk triage.
Search local envelope data and indexed bodies with filters (account, mailbox, dates, sender/recipient, unread, attachments).
Read single, batched, threaded, recent, and mailbox-listed messages; save attachments for inspection.
Refresh Mail.app and see before/after counts for new mail.
Send MIME email, reply with threading/history/reply-all/attachments, and create never-sent drafts.
Schedule, list, and cancel emails; support Exchange server-side delivery or a local queue.
Build reviewable triage plans for move/mark/flag actions, apply them once, and verify results; prepare capped deletion plans.
Create or delete mailboxes idempotently with live verification.
Run diagnostics/doctor, audit the local mutation ledger, and use read-only mode when configured.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apple-mail-mcp Find emails from John about the project proposal"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
✉️ apple-mail-mcp
Your Apple Mail, fully agent-operable.
Runs locally on your Mac. It opens the Mail store read-only, returns only what a client asks for, and sends only when the client explicitly calls the send tool. No third-party relay, no cloud copy of your mail.
uvx apple-mailbox-mcp setupMeasured on a 300k-message store: addressing one message 0.1 ms via Mail's own
index, against 7 to 10 s for the AppleScript whose-clause; full-text search
p95 under 1 ms. Method and script: docs/benchmarks.md.
Use Claude Code, Claude Desktop, Codex, Cursor, VS Code, or any local MCP client to search, read, triage, and send email through Apple Mail — your mailbox becomes something you can ask, search and delegate to — find anything in seconds, file hundreds of messages through a reviewed plan, send polished mail as the right identity, and let Exchange deliver scheduled messages even while your Mac is asleep.

✨ What you can do
🔍 Ask your mailbox questions. "What did Maria send me about the memo last week?" Search runs at database speed — sender, mailbox, dates, unread, attachments — and reconstructs whole conversations.
🕳️ Find what Mail itself can't. Mail's built-in search only skims the first line of most messages. apple-mail-mcp indexes every message body on your Mac — and for Exchange accounts it even fetches the bodies Mail never downloaded, straight from your own mailbox on the server. Queries that returned nothing return twenty.
🎭 Send as the right you. Work mail through the work lane, personal through Gmail — one parameter picks the identity. Every message is composed from scratch as clean, standards-correct email that renders everywhere, including Outlook (the AppleScript compose path that arrives blank in Outlook is the reason this project exists).
⏰ Schedule like "Send Later", but scriptable. A scheduled message is frozen in full — attachments, identity, exact text, and since 1.8.2 the threading headers, so a scheduled reply lands in the conversation it answers. Exchange can execute it server-side at the requested time, lid closed; other providers use a local background sender and deliver on its next pass (or just after the Mac wakes).
🗂️ Triage at scale, without fear. "File these 40 newsletters" becomes a reviewable plan: nothing moves until it is approved, every message is re-checked before it is touched, and the result is verified against Mail's own records afterward. Delete means Mail's Trash — nothing is ever erased.
📝 Draft where your drafts live. Compose into your real Exchange Drafts folder, ready to open in Outlook or OWA — created, never auto-sent.
Related MCP server: Mac Local Mail MCP
⚡ Why it's different
Every other Apple-Mail MCP drives AppleScript for both finding and acting. This one doesn't — and it shows:
Operation | AppleScript whose-clause | apple-mailbox-mcp |
🔍 Search 300k messages | seconds-to-timeout | milliseconds |
🎯 Address one message in a 71k mailbox | 7–10 s (measured) | < 0.1 ms |
✉️ Send mail | body renders blank in Outlook | renders everywhere, plain+HTML |
⏰ Schedule mail | — | server-side on Exchange; reliable local queue everywhere else |
🗂️ Bulk triage | one call per message, fire-and-forget | one reviewed plan, one apply, verified |
Every number above was measured on a live ~300,000-message store; the script and full method are in docs/benchmarks.md.
If the benchmarks hold up on your mailbox, a ⭐ helps others find this.
🛡️ Built to be trusted
✅ Plan → review → apply → verify. Bulk actions are frozen into a plan you can read before anything happens; the outcome is confirmed against Mail's own store afterward — never assumed.
🗑️ Nothing is ever erased. "Delete" files into Mail's Trash, and destructive plans have their own separate, capped door.
👓 Read-only mail mode. Set
EMAIL_MCP_READ_ONLY=1and only the 11 non-mutating mail tools exist in the session. Search may still maintain its local body index, and attachment retrieval writes the requested file to the configured temporary directory.💾 A crash-safe scheduled queue. Manifest updates are flushed and atomically replaced, so an interrupted rewrite keeps the last valid record. If a file is damaged independently, diagnostics name it instead of claiming the queue is empty, while healthy scheduled messages keep moving.
🧾 A local, best-effort activity ledger. Sends, schedules, cancellations and triage runs are recorded without making an unwritable log block mail. For reconciliation, the message itself, its Message-ID and its scheduled record remain authoritative.
🔒 No third-party mail relay. Mail content stays local except for mail you send and optional access to your own provider for Exchange/IMAP body backfill, drafts and server-side scheduling. SMTP passwords stay in the macOS Keychain or 1Password; Microsoft OAuth tokens live in a private 0600 cache under
~/.email-mcp/graph/.📜 A written contract. Since v1.0 every tool's shapes, error codes and caps evolve additively, held in place by 800+ automated tests.
🤝 Clear to every MCP client. All 21 tools identify what they do, explain every input, and declare whether they read, change or can remove data. Newer clients receive structured results; older clients keep the same JSON text. MCP SDK 2.2 and newer 2.x releases are tested, with support for older clients.
🧱 Built to evolve without breaking your workflow. Email rules are isolated from MCP, Mail.app, Exchange, delivery, and local storage. Provider or SDK changes stay at the edge while the 21-tool contract remains stable. The dependency rules are enforced in CI and explained in the architecture guide.
📦 Releases you can verify. Every tagged release is built and installed in a clean environment before publishing. GitHub includes the wheel, source archive, SHA-256 checksums and signed build provenance—not just source code.
🩺 Self-diagnosing.
apple-mail-mcp statusgives one readable readiness, scheduling and recovery screen.apple-mail-mcp doctorprovides the complete diagnostic detail and an exact fix for anything red.
🚀 Quick start
Grant Full Disk Access to your terminal app (System Settings → Privacy & Security → Full Disk Access), then quit and reopen the terminal. This is Apple's one manual toggle — there is no pop-up for it.
Install and set up:
uvx apple-mailbox-mcp setup # or: pipx install apple-mailbox-mcp # or via Homebrew: brew install parasxos/tap/apple-mail-mcp && apple-mail-mcp setupRegister with your client — one line for Claude Code:
claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcpor the same JSON block for Claude Desktop / Cursor / VS Code (
claude_desktop_config.json/.cursor/mcp.json/.vscode/mcp.json):{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }Verify:
uvx apple-mailbox-mcp statusprints one readiness screen — or just ask your client to run thedoctortool; every red line comes with its exact fix.uvx apple-mailbox-mcp --versionprints the installed version (apple-mailbox-mcp,apple-mail-mcpandemail-mcpare three names for the same command). The first body-index build on a large mailbox runs in the background and can take a few minutes; search works immediately and completes as the index fills.
Before running setup, grant your terminal app Full Disk Access
(System Settings → Privacy & Security → Full Disk Access) — that is how
reading stays fast and local. There is no pop-up for this one; it is Apple's
one manual toggle, and setup walks you to the exact pane if it finds it
missing.
setup asks everything in plain words (bare Enter accepts the recommended
answer), offers a sending identity, builds the body-search index, verifies
the nightly refresh actually runs, and ends by printing the one block you
paste into your MCP client:
{
"mcpServers": {
"apple-mail": { "command": "apple-mail-mcp" }
}
}Setup ends with a clear ready verdict or numbered recovery steps. Grant
Automation → Mail when triage first asks for it. Check the installation,
the next scheduled message, and failed scheduled sends anytime with
apple-mail-mcp status; use apple-mail-mcp doctor for the full technical detail.
💡 New to the terminal? Three things that look wrong and aren't:
brew install pipxwants a typedy(Enter alone is rejected);pipx ensurepathmay print a ⚠️ — the "pipx is ready to go!" line after it is the verdict; and afterensurepath, close and reopen the terminal once soapple-mail-mcpis found.
🔌 Works with
Every client below speaks stdio MCP; the command is always uvx apple-mailbox-mcp.
Claude Code
claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcpClaude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{ "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }Cursor
Add the same block to ~/.cursor/mcp.json (or per-project .cursor/mcp.json).
VS Code (Copilot MCP)
Add the same block under "servers" in .vscode/mcp.json.
Codex CLI
# ~/.codex/config.toml
[mcp_servers.apple-mail]
command = "uvx"
args = ["apple-mailbox-mcp"]Any stdio MCP client
Point it at uvx apple-mailbox-mcp. The wire contract is additive-only since v1.0.
🔧 Troubleshooting
Symptom | Fix |
Client says the server failed to start, but | GUI apps don't inherit your shell PATH. Use the absolute path: |
| Full Disk Access is missing for the app that launches the server (the client, not the terminal). Grant it, then fully quit and reopen that app. |
Search finds recent mail but not bodies of old mail | The body index is still building — first build on a 100k+ mailbox takes minutes. |
Send fails with | Run |
Triage does nothing the first time | Grant Automation → Mail when macOS asks; the prompt appears on first use, not at install. |
🧰 The 21 tools
Group | Tools |
🔍 Read (8) |
|
✉️ Send (6) |
|
🗂️ Triage (5) |
|
🩺 Meta (2) |
|
Attachments both ways, size-budgeted. Replies thread correctly in every client. Scheduling survives sleep — a message due while the lid was closed goes out on the first tick after wake, or exactly on time via Exchange.
🎭 Your addresses, your lanes
The From: address decides how mail travels. ~/.email-mcp/identities.toml:
default = "work"
[work] # sent through a host you already trust, over SSH
from_addr = "you@example.org"
driver = "ssh_sendmail"
host = "bastion.example.org" # any login host you already SSH to
[gmail] # classic SMTP — the app password stays in 1Password
from_addr = "you@gmail.com"
driver = "smtp"
host = "smtp.gmail.com"
op = "op://Personal/gmail app password/password"Exchange identities can add one sign-in to unlock the extras: drafts filed in
your real Drafts folder, and scheduled sends executed by the server itself —
lid closed, Mac asleep. setup offers it in one plain question. Reading
needs no sending configuration at all.
21 tools · over 1,200 tests · additive wire contract since v1.0 Live-calibrated end-to-end on a 305k-message store.
Built for one Mac — and for anyone else whose Mac runs Mail.app.
Available Tools
21 toolsauditRead the activity historyARead-onlyIdempotent
Read the local mutation ledger with time, tool, event, plan, and operation filters.
Inputs: tool, event, limit, since, +3 more. Returns: object
cancel_scheduledCancel a scheduled emailADestructiveIdempotent
Revoke a pending scheduled email locally and, when needed, in Exchange.
Inputs: id (required). Returns: object
create_draftCreate an email draftA
Create a never-sent draft in the selected identity's server-side Drafts folder.
Inputs: to (required), body (required), subject (required), cc, +2 more. Returns: object
doctorCheck email setupARead-onlyIdempotent
Diagnose permissions, identities, transports, scheduling, storage, and indexing.
Inputs: no named parameters. Returns: object
get_attachmentSave an attachment for readingARead-onlyIdempotent
Save one attachment to the configured temporary directory for reading.
Inputs: id (required), attachment_id (required). Returns: object
get_emailRead an emailARead-onlyIdempotent
Read one email by envelope ID at full, metadata, or minimal detail.
Inputs: id (required), view. Returns: object
get_emails_batchRead multiple emailsARead-onlyIdempotent
Read up to 50 emails in one bounded request, with per-ID errors.
Inputs: ids (required), view. Returns: object
get_threadRead an email threadARead-onlyIdempotent
Return the messages in one conversation in chronological order.
Inputs: thread_id (required). Returns: object
list_mailboxesList mailboxesARead-onlyIdempotent
List configured mailboxes with server and locally readable counts.
Inputs: no named parameters. Returns: object
list_recentList recent emailsCRead-onlyIdempotent
List recent messages, optionally scoped to an account and mailbox.
Inputs: limit, account, mailbox. Returns: object
list_scheduledList scheduled emailsARead-onlyIdempotent
List healthy and damaged scheduled-mail records by lifecycle state.
Inputs: limit, state. Returns: object
mailbox_createCreate a mailboxAIdempotent
Create a mailbox idempotently and report live and index verification.
Inputs: path (required), account (required). Returns: object
mailbox_deleteDelete a mailboxADestructiveIdempotent
Delete an empty mailbox only, with live verification and safe fallback.
Inputs: path (required), account (required). Returns: object
refresh_mailRefresh mailARead-onlyIdempotent
Ask Mail.app to fetch new mail and report the before/after snapshot.
Inputs: wait_seconds, timeout_seconds. Returns: object
reply_emailReply to an emailB
Reply with correct threading, optional history, attachments, and reply-all.
Inputs: id (required), body (required), cc, bcc, +4 more. Returns: object
schedule_emailSchedule an emailB
Freeze an email now and schedule local or Exchange-side delivery.
Inputs: to (required), body (required), send_at (required), subject (required), +6 more. Returns: object
search_emailsSearch emailsARead-onlyIdempotent
Search local envelope data and indexed body content. Check the returned FTS coverage before treating no matches as proof that no email exists. Sender filters are case-insensitive substring matches.
Inputs: after, limit, query, before, +7 more. Returns: object
send_emailSend an emailB
Compose standards-correct MIME and send it through the selected identity.
Inputs: to (required), body (required), subject (required), cc, +3 more. Returns: object
triage_applyApply reviewed mailbox changesADestructiveIdempotent
Apply one reviewed plan, optionally excluding selected envelope IDs, and verify the retained messages. A successful claim consumes the whole plan once.
Inputs: plan_id (required), exclude_ids. Returns: object
triage_planPrepare mailbox changesA
Prepare a reviewable bulk-change plan; sender filters use case-insensitive substring matching.
Inputs: after, limit, query, before, +7 more. Returns: object
triage_plan_deletePrepare email deletionB
Prepare a capped Trash plan whose sender filter is exact, never a broad substring match.
Inputs: after, limit, query, before, +6 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools are clearly distinct: send, reply, schedule, and draft are separate, while read operations are split by single, batch, thread, search, and recent listing. Minor overlap exists between triage_plan and triage_plan_delete, and between search_emails and list_recent, but descriptions clarify their boundaries.
Most names follow verb_noun (get_email, list_mailboxes, send_email), but mailbox_create/mailbox_delete reverse the order, triage tools mix noun and verb patterns, and doctor/audit are bare nouns. The set remains readable, but the convention is not fully consistent.
At 21 tools, the surface is borderline heavy for an email client, though many map to legitimate lifecycle operations. It also includes niche diagnostic and audit tools, pushing it into the 16-25 range that feels somewhat over-scoped.
Core email lifecycle is well covered: send, reply, draft, schedule, search, read, batch, thread, attachments, mailbox management, triage, audit, and diagnostics. Missing forward_email and direct draft editing or flagging are minor gaps that most agents can work around.
Maintenance
Related MCP Connectors
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseAqualityDmaintenanceA local MCP server for searching and reading downloaded Apple Mail data without changing mail state.8MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to search, read, and inspect Apple Mail on macOS, including conversations and attachments. It can create new, reply, reply-all, or forward drafts, but cannot send or modify existing messages.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that gives an AI assistant access to IMAP/SMTP mailboxes to read, search, organize, draft, and send email, with local mirroring and full-text search, no third-party data path, and credentials stored only in the macOS Keychain.11 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables searching, reading full conversations, and sending email across multiple IMAP/SMTP mailboxes from any MCP client, with multi-user support and per-user API tokens.MIT