imdinu/apple-mail-mcp

The only Apple Mail MCP server with **full-coverage body search** — reliable on large mailboxes where AppleScript-based servers timeout. 8 tools for reading, searching, and extracting email content.
**Read the docs** for the full guide.
Quick Start
Claude Code (plugin)
Claude Desktop (one-click bundle)
Download apple-mail-mcp- .mcpb from the
latest release
and double-click it.
Both the plugin and the bundle run the released PyPI package via a thin
launcher (uvx → pipx → private venv, whichever is available) — no
vendored code, identical behavior to a manual install. They start the
server with --watch; grant Full Disk Access to the launching app
(Claude Code / Claude Desktop) so the index stays fresh.
Any MCP client
Add to your MCP client:
Build the Search Index (Recommended)
Configure (Optional)
Writes a commented config file you can edit to set defaults like your
primary account or mailbox. Every key has a matching APPLE_MAIL_* env
var if you prefer environment-based config. See
Configuration
for the full schema and precedence rules.
Tools
| Tool | Purpose |
|------|---------|
| list_accounts() | List email accounts |
| list_mailboxes(account?) | List mailboxes |
| get_emails(filter?, limit?) | Get emails — all, unread, flagged, today, last_7_days |
| get_email(message_id) | Get single email with full content + attachments |
| search(query, scope?, before?, after?, highlight?) | Search — all, subject, sender, body, attachments |
| get_email_links(message_id) | Extract links from an email |
| get_email_attachment(message_id, filename) | Extract attachment content |
| get_attachment(message_id, filename) | *Deprecated* — use get_email_attachment() |
Performance
Tested against 6 other Apple Mail MCP servers on a real **~73K-message** mailbox:
- **Only server with full-coverage body search.** Most competitors don't support body search at all; the one that does (BastianZim) live-scans only the 5000 most recent messages — silent miss on anything older. Our FTS5 index covers the entire mailbox.
- **~3ms single email fetch** via disk-first .emlx reading (no JXA round-trip).
- **~1ms list_accounts and ~5ms 50-email listing** via direct Envelope-Index SQLite reads (0.4+) — same path BastianZim/rusty/pl-lyfx use, with JXA as the correctness fallback.
- **~7ms subject search** via FTS5 — competitive with native Rust on the same operation.
- **Reliable across all 6 benchmarked operations** on a 73K mailbox; AppleScript-based servers timeout, throw syntax errors, or skip operations they don't support.