apple-mail-mcp

Purpose

apple-mail-mcp is a locally running MCP (Model Context Protocol) server that turns Apple Mail on macOS into a tool that can be operated by AI clients. You can use Claude Code, Claude Desktop, Codex, Cursor, VS Code, or any local MCP client to ask questions about, search, organize, and send email. The program runs locally on the Mac, opens the Mail store in read-only mode, returns only the content explicitly requested by the client, and sends mail only when the client explicitly invokes the send tool. There is no third-party relay, and no cloud copy of email.

Main capabilities

• Extremely fast search: addressing a single email through Mail's built-in SQLite index takes about 0.1 ms (AppleScript's whose clause takes 7 to 10 seconds), and full-text search p95 is under 1 ms. The measured data is based on a mail store of about 300,000 emails; the methodology and scripts are in docs/benchmarks.md.
• Fills in what Mail cannot find: Mail's built-in search mostly scans only the first line, while this tool indexes each email body locally; for Exchange accounts, it also pulls from the server's own mailbox the bodies that Mail never downloaded.
• Multi-identity sending: choose the From address with a single parameter, so work email goes through the work identity and personal email goes through Gmail. Each email is composed from scratch as a clean, standards-compliant message that renders correctly everywhere, including Outlook.
• Scheduled sending: scheduled messages are fully frozen, including attachments, identity, exact text, and since 1.8.2 also threading headers. Exchange can execute server-side at the specified time (it works even with the lid closed), while other providers use a local background sender at the next delivery round (or after the Mac wakes).
• Batch organizing: turns "archive these 40 newsletters" into a reviewable plan, moves no email without approval, rechecks each email before acting, and verifies results against Mail's own records. Deletion means moving to Mail's Trash, never actually erasing.
• Drafts: composed into the real Exchange Drafts folder, openable in Outlook or OWA, only creating and never auto-sending.

How to use

1. Grant the terminal app "Full Disk Access" (System Settings → Privacy &Security → Full Disk Access), then quit and reopen the terminal; this is Apple's only manual switch, with no pop-up.
2. 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 setup
3. Register with the client (using Claude Code as an example): claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp Claude Desktop / Cursor / VS Code use the same JSON block (claude_desktop_config.json / .cursor/mcp.json / .vscode/mcp.json): { "mcpServers": { "apple-mail": { "command": "uvx", "args": ["apple-mailbox-mcp"] } } }
4. Verify: uvx apple-mailbox-mcp status prints a readiness screen, or have the client run the doctor tool; red items come with the exact fix. For large mailboxes, the first build of the body index runs in the background and may take several minutes; search is available immediately and becomes complete as the index improves.

setup asks about everything in plain language (press Enter to accept the recommended answer), provides sending identities, builds the body search index, verifies that the nightly refresh actually runs, and finally prints the code block to paste into the MCP client. Organizing requires granting "Automation → Mail" permission the first time it is needed. You can use apple-mail-mcp status at any time to check the installation, the next scheduled message, and failed scheduled sends; use apple-mail-mcp doctor for full technical details.

Suitable scenarios

Suitable for Mac users who want to use an AI client to quickly search, read, organize, and send Apple Mail emails, especially mailScenarios with large mailbox scale and requirements for search speed and multi-identity sending. Supports Exchange account body completion, drafts, and server-side scheduled sending.

Limitations and trust design

• Read-only mail mode: After setting EMAIL_MCP_READ_ONLY=1, only 11 non-mutating mail tools exist in the session. Search may still maintain a local body index, and attachment retrieval will write the requested files to the configured temporary directory.
• Plan -> Review -> Apply -> Verify: Batch operations are frozen into readable plans, checked afterward against Mail's own storage, and results are never assumed.
• Crash-safe scheduled queue: Manifest updates are flushed to disk and atomically replaced; interrupted rewrites retain the last valid record.
• Local activity ledger: Sends, schedules, cancellations, and organization runs are recorded, but a non-writable log will not block mail; reconciliation relies on the mail itself, its Message-ID, and the scheduled records.
• No third-party mail relay: Mail content stays local unless it is mail you send, and unless there is optional access to your own provider for Exchange/IMAP body completion, drafts, and server-side scheduling. SMTP passwords are stored in the macOS Keychain or 1Password; Microsoft OAuth tokens are stored in a private cache under ~/.email-mcp/graph/ with permissions 0600.
• Written contract: Since v1.0, each tool's shape, error codes, and limits evolve additively, safeguarded by more than 800 automated tests (official text elsewhere mentions more than 1,200 tests and 849 tests; the specific numbers are subject to the repository).
• All 21 tools indicate their purpose, explain every input, and declare whether they read, change, or may delete data. Newer clients receive structured results, while older clients retain the same JSON text.
• Self-diagnostics: apple-mail-mcp status provides readiness, scheduling, and recovery views; apple-mail-mcp doctor provides full diagnostic details and the exact fix for red items.

Other notes

The project uses the MIT License and has been tested end-to-end on a store of about 300,000 emails. If it helps after installation, you can star it on GitHub. Other detailed information can be found in the repository's docs/benchmarks.md and the architecture guide.