apple-mail-mcp is an MCP (Model Context Protocol) server for Apple Mail, positioned to solve the problem of reading and searching emails in large mailbox scenarios. The official introduction calls it "the only Apple Mail MCP server with full-coverage body search," and it remains reliable on large mailboxes where AppleScript-based servers time out.
Purpose and positioning The project is used to let AI clients (such as Claude Code and Claude Desktop) connect to local Apple Mail to read, search, and extract email content. It provides 8 tools, covering operations such as reading, searching, and attachment extraction.
Main capabilities
- List accounts and mailboxes: implemented by directly reading the Envelope-Index SQLite; the official description says list_accounts completes in about 1 ms, and listing 50 emails completes in about 5 ms, with JXA as a correctness fallback.
- Fetch emails: uses a disk-first .emlx reading approach, with no JXA round trip; the official description says reading a single email takes about 3 ms.
- Full-text search: based on an FTS5 index, covering the entire mailbox; the official description says subject search takes about 7 ms. The author compared it with 6 other Apple Mail MCP servers on a real mailbox of about 73,000 emails, and says most competitors do not support body search, and the only one that does (BastianZim) only scans the most recent 5,000 emails in real time, silently missing older emails, whereas this project's FTS5 index covers the entire mailbox.
- Attachment extraction: can extract attachments.
How to use
- Installation method one: Claude Code plugin.
- Installation method two: Claude Desktop one-click package; download apple-mail-mcp-<version>.mcpb from the latest release and double-click it. Both the plugin and the one-click package run the published PyPI package through a lightweight launcher (uvx → pipx → private venv, whichever is available), do not bundle vendored code, and behave the same as a manual installation. Both start the server with --watch; the launching application (Claude Code / Claude Desktop) needs to be granted Full Disk Access to ensure the index stays up to date.
- Add it to an MCP client (see the documentation for the specific configuration).
- Recommended step: build the search index (Recommended); optional configuration: after running, write an annotated configuration file, which can be edited to set the default primary account or mailbox; each key has a corresponding APPLE_MAIL_* environment variable, making it easy to configure via environment variables. Configuration priority is CLI > env > file > default.
- All tools also provide standalone CLI commands, so there is no need to run the MCP server, and all commands output JSON. A Claude Code skill for CLI access can be generated.
Applicable scenarios When you need to retrieve, read, and extract local Apple Mail emails in an AI client, especially in scenarios where the mailbox is large and AppleScript-based solutions time out or miss older emails.
Limitations and notes The official description emphasizes its reliability and speed advantages on a 73K mailbox; when using the plugin or one-click package, Full Disk Access must be granted, otherwise the index may not stay up to date. The specific parameters and output structures for attachment extraction and account/mailbox operations are not yet provided. The project license is GPL-3.0-or-later. Price and billing information is not provided in the original text.
