Apple Mail MCP

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

GitHub

Apple Mail MCP

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

A fast MCP server for Apple Mail — 87x faster email fetching via batch JXA, plus 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

ToolPurpose
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

ScenarioApple Mail MCPBest alternativeSpeedup
Fetch 50 emails529ms15,288ms29x
Body search~2ms~7,000ms (or unsupported)3500x
List accounts108ms146msFastest

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

Configuration

VariableDefaultDescription
APPLE_MAIL_DEFAULT_ACCOUNTFirst accountDefault email account
APPLE_MAIL_DEFAULT_MAILBOXINBOXDefault mailbox
APPLE_MAIL_INDEX_PATH~/.apple-mail-mcp/index.dbIndex location
APPLE_MAIL_INDEX_EXCLUDE_MAILBOXESDraftsMailboxes to skip in search
{
  "mcpServers": {
    "mail": {
      "command": "apple-mail-mcp",
      "args": ["--watch"],
      "env": {
        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
      }
    }
  }
}

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

Related Servers