uvx apple-mailbox-mcp setup

✨ 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. 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.

⚡ Why it's different

Every other Apple-Mail MCP drives AppleScript for both finding and acting.
This one doesn't — and it shows:

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=1 and 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.
  Both the maintained MCP 1.x line and current MCP 2.x are tested.
• 🧱 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 status gives one readable readiness,
  scheduling and recovery screen. apple-mail-mcp doctor provides the complete
  diagnostic detail and an exact fix for anything red.

🚀 Quick start

1. 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.

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 your client — one line for Claude Code:

   claude mcp add --transport stdio --scope user apple-mail -- uvx apple-mailbox-mcp
   

   or 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"] }
     }
   }
   

4. Verify: uvx apple-mailbox-mcp status prints one readiness screen —
   or just ask your client to run the doctor tool; every red line comes
   with its exact fix. 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 pipx wants a typed y (Enter alone is rejected);
pipx ensurepath may print a ⚠️ — the "pipx is ready to go!" line after it
is the verdict; and after ensurepath, close and reopen the terminal once
so apple-mail-mcp is 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-mcp

Claude 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

🧰 The 21 tools

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 = "[email protected]"
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 = "[email protected]"
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.