Apple Mail MCP

★ 45

from imdinu

Fast MCP server for Apple Mail with batch JXA (87x faster) and FTS5 search index (700-3500x faster).

🔥🔥🔥🔥✓ VerifiedFreeQuick setup

#email #payments #database #documents #git #security

Apple Mail MCP

<p align="center"> <img src="docs/assets/social-card.svg" alt="Apple Mail MCP — Full-coverage FTS5 body search" width="720"> </p>

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.

Tools

Tool	Purpose
`list_accounts()`	List email accounts
`list_mailboxes(account?)`	List mailboxes
`get_emails(filter?, limit?)`	Get emails — all, unread, flagged, today, last_7_days
`get_email(message_id)`	Get single email with full content + attachments
`search(query, scope?, before?, after?, highlight?)`	Search — all, subject, sender, body, attachments
`get_email_links(message_id)`	Extract links from an email
`get_email_attachment(message_id, filename)`	Extract attachment content
`get_attachment(message_id, filename)`	Deprecated — use `get_email_attachment()`

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

Development

Copy & paste — that's it

git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytest

License

GPL-3.0-or-later

Copy & paste — that's it

pipx install apple-mail-mcp

Before it works, you'll need: APPLE_MAIL_DEFAULT_ACCOUNT

Quick Start

Copy & paste — that's it

pipx install apple-mail-mcp

Add to your MCP client:

Copy & paste — that's it

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

Build the Search Index (Recommended)

Copy & paste — that's it

# Requires Full Disk Access for Terminal
# System Settings → Privacy & Security → Full Disk Access → Add Terminal

apple-mail-mcp index --verbose

Configure (Optional)

Copy & paste — that's it

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.

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:

Copy & paste — that's it

{
  "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):

Copy & paste — that's it

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

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

Copy & paste — that's it

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