apple-mail-mcp 0.1.7

Fast MCP server for Apple Mail with disk-first reads, batch JXA, and FTS5 search

Apple Mail MCP

A fast MCP server for Apple Mail — disk-first email reading, 87x faster batch fetching via JXA, and an FTS5 search index for 700–3500x faster body search (~2ms vs ~7s).

Read the docs for the full guide.

Quick Start

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

Tools

Tool	Purpose
list_accounts()	List email accounts
list_mailboxes(account?)	List mailboxes
get_emails(filter?, limit?)	Get emails — all, unread, flagged, today, this_week
get_email(message_id)	Get single email with full content + attachments
search(query, scope?)	Search — all, subject, sender, body, attachments
get_attachment(message_id, filename)	Extract attachment content (base64)

Performance

Scenario	Apple Mail MCP	Best alternative	Speedup
Fetch single email	6ms	unsupported	Only one (disk-first)
Fetch 50 emails	301ms	13,800ms+	46x faster
Search (subject)	10ms	148ms	15x faster
Search (body)	22ms	unsupported	Only one
List accounts	118ms	134ms	Fastest

Benchmarked against 5 other Apple Mail MCP servers at the MCP protocol level.

Configuration

Variable	Default	Description
APPLE_MAIL_DEFAULT_ACCOUNT	First account	Default email account
APPLE_MAIL_DEFAULT_MAILBOX	INBOX	Default mailbox
APPLE_MAIL_INDEX_PATH	~/.apple-mail-mcp/index.db	Index location
APPLE_MAIL_INDEX_MAX_EMAILS	5000	Max emails indexed per mailbox
APPLE_MAIL_INDEX_EXCLUDE_MAILBOXES	Drafts	Mailboxes to skip in search

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

Migrating from apple-mcp?

If you used supermemoryai/apple-mcp (archived January 2026), apple-mail-mcp is a maintained alternative for the Mail portion specifically. Notes, Messages, Contacts, Calendar, and Reminders are out of scope.

apple-mcp (mail tool, action)	apple-mail-mcp
read_emails	get_emails(filter?, limit?) + get_email(message_id)
search_emails	search(query, scope?) — 5 scopes: all, subject, sender, body, attachments
send_email	Not yet supported (planned)

What's different: available on PyPI (pipx install apple-mail-mcp), disk-first single-email reads (~1-5ms via .emlx parsing), 87x faster batch fetching via JXA, FTS5 search index for ~2ms body search, and disk-based sync that avoids JXA timeouts and false-success responses.

Development

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