apple-mail-mcp

✨ What you can do

🔍 Ask your mailbox questions. *"What did Stefan 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:

> `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 = "you@example.org"
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 = "you@gmail.com"
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.