A
licenseNot graded
qualityD
maintenanceA read-only MCP server for Apple Mail on macOS that enables searching and reading emails directly from the local SQLite database, with fast SQL-level filtering and pagination.
2
MIT
Apple Mail MCP
by imdinu
This server provides MCP tools for listing Apple Mail accounts/mailboxes and retrieving/filtering/searching emails.
list_accounts()— list configured email accounts.list_mailboxes(account?)— list mailboxes with unread counts.get_emails(account?, mailbox?, limit?)— fetch recent emails (newest first).get_todays_emails(account?, mailbox?)— fetch emails received today.get_unread_emails(account?, mailbox?, limit?)— fetch unread emails.get_flagged_emails(account?, mailbox?, limit?)— fetch flagged emails.search_emails(query, account?, mailbox?, limit?)— search emails by query in subject/sender.
Enables programmatic interaction with Apple Mail on macOS, allowing for listing accounts and mailboxes, fetching recent, unread, or flagged emails, and searching for messages by sender or subject.
Allows for managing and retrieving email content from iCloud accounts configured within the Apple Mail application.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Apple Mail MCP Show me my unread emails from today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Apple Mail MCP
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-mcp
claude plugin install apple-mail@imdinuClaude 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-mcpAdd 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 --verboseConfigure (Optional)
apple-mail-mcp init # writes ~/.apple-mail-mcp/config.tomlWrites 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.
Related MCP server: macos-mcp
Tools
Tool | Purpose |
| List email accounts |
| List mailboxes |
| Get emails — all, unread, flagged, today, last_7_days |
| Get single email with full content + attachments |
| Search — all, subject, sender, body, attachments |
| Extract links from an email |
| Extract attachment content |
| Deprecated — use |
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
.emlxreading (no JXA round-trip).~1ms
list_accountsand ~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.
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 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.pdfAll commands output JSON. Generate a Claude Code skill for CLI-based access:
apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.mdDevelopment
git clone https://github.com/imdinu/apple-mail-mcp
cd apple-mail-mcp
uv sync
uv run ruff check src/
uv run pytestLicense
GPL-3.0-or-later
Available Tools
7 toolsget_emailsA
Get emails from a mailbox.
Retrieves emails with standard properties: id, subject, sender, date_received, read status, and flagged status.
Args: account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified. limit: Maximum number of emails to return (default: 50)
Returns: List of email dictionaries sorted by date (newest first).
Example: >>> get_emails("Work", "INBOX", limit=10) [{"subject": "Meeting tomorrow", "sender": "boss@work.com", ...}, ...]
Inputs: account, mailbox, limit. Returns: result
get_flagged_emailsA
Get flagged emails from a mailbox.
Args: account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified. limit: Maximum number of emails to return (default: 50)
Returns: List of flagged emails sorted by date (newest first).
Example: >>> get_flagged_emails("Work") [{"subject": "Important task", "flagged": true, ...}, ...]
Inputs: account, mailbox, limit. Returns: result
get_todays_emailsA
Get all emails received today from a mailbox.
Args: account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified.
Returns: List of today's emails sorted by date (newest first).
Example: >>> get_todays_emails("Work") [{"subject": "Urgent: Review needed", "sender": "team@work.com", ...}]
Inputs: account, mailbox. Returns: result
get_unread_emailsA
Get unread emails from a mailbox.
Args: account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified. limit: Maximum number of emails to return (default: 50)
Returns: List of unread emails sorted by date (newest first).
Example: >>> get_unread_emails("Work", limit=20) [{"subject": "New message", "read": false, ...}, ...]
Inputs: account, mailbox, limit. Returns: result
list_accountsA
List all configured email accounts in Apple Mail.
Returns: List of account dictionaries with 'name' and 'id' fields.
Example: >>> list_accounts() [{"name": "Work", "id": "abc123"}, {"name": "Personal", "id": "def456"}]
Inputs: no named parameters. Returns: result
list_mailboxesA
List all mailboxes for an email account.
Args: account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified.
Returns: List of mailbox dictionaries with 'name' and 'unreadCount' fields.
Example: >>> list_mailboxes("Work") [{"name": "INBOX", "unreadCount": 5}, ...]
Inputs: account. Returns: result
search_emailsA
Search for emails matching a query string.
Searches in both subject and sender fields (case-insensitive).
Args: query: Search term to look for account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or first account if not specified. mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or "Inbox" if not specified. limit: Maximum number of results (default: 50)
Returns: List of matching emails sorted by date (newest first).
Example: >>> search_emails("invoice", "Work") [{"subject": "Invoice #123", "sender": "billing@vendor.com", ...}]
Inputs: query (required), account, mailbox, limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
A3.8/5.0
Scored across 7 tools
Disambiguation2/5
Multiple tools have overlapping purposes that could cause confusion. get_emails, get_flagged_emails, get_todays_emails, and get_unread_emails all retrieve emails with different filters, but their boundaries are unclear—an agent might struggle to choose between them when multiple criteria apply. The descriptions help somewhat, but the functional overlap is significant.
Naming Consistency5/5
Tool names follow a consistent verb_noun pattern throughout (e.g., get_emails, list_accounts, search_emails). All tools use snake_case with clear, descriptive names that align with their functions, making the set predictable and easy to understand.
Tool Count5/5
With 7 tools, the count is well-scoped for an email management server. Each tool serves a distinct, useful purpose in the domain (e.g., retrieving emails, listing accounts/mailboxes, searching), and none feel redundant or missing in terms of quantity for the apparent scope.
Completeness2/5
There are significant gaps in the tool surface for email management. The server lacks essential CRUD operations like creating, sending, updating (e.g., marking as read/unread), or deleting emails, which are core to the domain. This will likely cause agent failures when trying to perform common email tasks beyond retrieval and listing.
Maintenance
ActivityMaintained
ResponsivenessMixed handling
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Programmable email inbox for AI agents — JMAP, PoW auth, stdio MCP server.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Related MCP Servers
- AlicenseBqualityDmaintenanceLocal MCP server for macOS native apps: Mail, Calendar, Reminders, Notes, Messages, and Contacts. Enables reading and organizing your Mac life through a single stdio process using AppleScript/JXA.4021 npm1MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that drives macOS Mail: read, search, send, organise.MIT
- AlicenseAqualityDmaintenanceA local MCP server that lets Claude read macOS Mail.app via JXA, with tools for listing accounts/mailboxes, searching and reading messages. Read-only by default, with optional opt-in write tools for compose drafts and Apple Calendar events.7MIT