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
Tools 6
list_accountsList email accountslist_mailboxesList mailboxesget_emailsGet emails — all, unread, flagged, today, this_weekget_emailGet single email with full content + attachmentssearchSearch — all, subject, sender, body, attachmentsget_attachmentExtract attachment content (base64)Environment Variables
APPLE_MAIL_DEFAULT_ACCOUNTDefault email accountAPPLE_MAIL_DEFAULT_MAILBOXDefault mailboxAPPLE_MAIL_INDEX_PATHIndex locationAPPLE_MAIL_INDEX_MAX_EMAILSMax emails indexed per mailboxAPPLE_MAIL_INDEX_EXCLUDE_MAILBOXESMailboxes to skip in search