Apple Mail MCP

Apple Mail MCP

[Apple Mail MCP — Full-coverage FTS5 body search]

[Python 3.11+] [License: GPL v3] [macOS] [MCP] [Code style: ruff] [CI]

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 plugin marketplace add imdinu/apple-mail-mcpclaude plugin install apple-mail@imdinu

Claude Desktop (one-click bundle)

Download apple-mail-mcp-<version>.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

pipx install apple-mail-mcp

Add to your MCP client:

{  "mcpServers": {    "mail": {      "command": "apple-mail-mcp"    }  }}

Build the Search Index (Recommended)

# Requires Full Disk Access for Terminal# System Settings → Privacy & Security → Full Disk Access → Add Terminal
apple-mail-mcp index --verbose

Configure (Optional)

apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

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

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.

[Capability Matrix]

Configuration

Apple Mail MCP works out of the box. To customize defaults, run apple-mail-mcp init to generate a config.toml template — or use the matching APPLE_MAIL_* environment variables. See the Configuration docs for the full schema and the CLI > env > file > default precedence.

Per-client env overrides via the MCP client's launch config also work:

{  "mcpServers": {    "mail": {      "command": "apple-mail-mcp",      "args": ["--watch"],      "env": {        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"      }    }  }}

CLI Usage

All tools are also available as standalone CLI commands (no MCP server needed):

apple-mail-mcp search "quarterly report" --scope subjectapple-mail-mcp search "invoice" --after 2026-01-01 --limit 10apple-mail-mcp read 12345apple-mail-mcp emails --filter unread --limit 10apple-mail-mcp accountsapple-mail-mcp mailboxes --account Workapple-mail-mcp extract 12345 invoice.pdf

All commands output JSON. Generate a Claude Code skill for CLI-based access:

apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

Development

git clone https://github.com/imdinu/apple-mail-mcpcd apple-mail-mcpuv syncuv run ruff check src/uv run pytest

License

GPL-3.0-or-later