apple-mail-mcp

A read-only MCP server that lets an AI assistant search and read the mail in Apple Mail.

macOS only. It reads the local index that Mail.app keeps on your Mac.

claude mcp add apple-mail -- npx -y @redpop/apple-mail-mcp

Then grant Full Disk Access once with npx -y @redpop/apple-mail-mcp setup. For Claude Desktop there is a one-click bundle: see Install.

What it does

The main use is "find the mail about X":

"Find the mail from the landlord about the heating bill"
"What did Anna send me last week with an attachment?"
"Show the whole thread about the contract renewal"

Four tools: list_mailboxes, search_messages, get_message, get_thread. Search covers sender, recipient, subject, free text, mailbox, date range, unread, flagged and attachments, and can also look inside message bodies. Results carry a message:// link that opens the mail in Mail.app, where Mail stores the Message-ID (not on macOS 15). Details: docs/tools.md.

Why this one

• Fast. It queries Mail's SQLite index instead of scripting Mail.app with AppleScript. On one real mailbox with about 240,000 message rows, a page of search results takes 4 to 90 ms in the helper, a subject search 25 ms after the first one; see docs/architecture.md for the measurements and their limits.
• Full Disk Access goes to a small helper, not to your terminal or your AI client. The server reaches Mail's files through a small app, "Mail MCP Helper", and macOS binds the permission to that app alone. Node, Terminal and Claude never get it.
• Read-only by construction, not by a flag. There is no code that sends, drafts, moves, deletes or flags mail, none that opens the database for writing, and none that opens a network connection.
• Mail.app does not have to be running and no Automation prompt appears. Your data is only as fresh as Mail's last sync, though, and a message that Mail never downloaded has no body.
• Threads and deep links. get_thread returns a conversation; messages carry a message:// link (not on macOS 15).
• Security mails are withheld by default. Messages that look like verification codes, password resets or sign-in links are shown without their body, with digits in the subject masked, and cannot be found by body search. Detection is best effort, not a guarantee.
• Settings come from configuration, never from tool parameters, so a malicious mail cannot ask the model to switch them off.
• Works with apple-calendar-mcp: "find the mail about Thursday's meeting". Same conventions: timestamps in ISO 8601 with offset, and errors as an isError result with one plain-English sentence per error code.

Moving mail

This package stays read-only. A separate package, @redpop/apple-mail-actions-mcp, adds one tool that moves messages between mailboxes of one account. It runs beside this server and is not installed with it.

Requirements

• macOS 15 or later. Verified with a real mailbox only on macOS 27.0.1 with Mail 16.0. The database layout of macOS 15.8 and 26.6 passes the helper's column check, taken from runners without a mail account. On macOS 15 Mail stores no Message-ID header, so results there carry no message:// link. Support depends on the layout of Mail's database, not on the version number: doctor checks it. Reports from other versions are welcome, see Reporting problems.
• Node.js 22.16 or newer in the 22 line, or 24 and newer.
• Mail set up with at least one account.
• Exchange accounts are untested. Mailboxes and message metadata are listed, but bodies of Exchange mail are not read yet: get_message reports file_not_found. See docs/exchange.md.

Security model in short

A mailbox holds secrets: code

... View full README on GitHub