Tools¶

Apple Mail MCP provides 8 MCP tools — a consolidated API designed for AI assistants.

Overview¶

list_accounts()¶

List all configured email accounts in Apple Mail.

Parameters: None

Returns: List of accounts with name and id fields.

list_accounts()
# → [{"name": "Work", "id": "abc123"}, {"name": "Personal", "id": "def456"}]

list_mailboxes()¶

List all mailboxes for an email account.

Parameters:

Returns: List of mailboxes with name and unreadCount fields.

list_mailboxes()
# → [{"name": "INBOX", "unreadCount": 5}, {"name": "Sent", "unreadCount": 0}]

list_mailboxes("Work")
# → [{"name": "INBOX", "unreadCount": 12}, ...]

get_emails()¶

Get emails from a mailbox with optional filtering. This is the primary tool for listing emails.

Parameters:

Filters:

Returns: List of email summaries sorted by date (newest first), each with: id, subject, sender, date_received, read, flagged.

get_emails()
# All emails from default mailbox

get_emails(filter="unread", limit=10)
# 10 most recent unread emails

get_emails("Work", "INBOX", filter="today")
# Today's work emails

get_email()¶

Get a single email with full content. Uses a 3-strategy cascade to find the message:

1. Try the specified mailbox directly
2. Look up the email's location in the FTS5 index
3. Iterate all mailboxes with per-mailbox error handling

Parameters:

Returns: Full email with: id, subject, sender, content (full body text), date_received, date_sent, read, flagged, reply_to, message_id (RFC 822 Message-ID header), attachments (list of {filename, mime_type, size}).

get_email(12345)
# → {"id": 12345, "subject": "Meeting notes", "content": "Hi team,...",
#    "attachments": [{"filename": "notes.pdf", "mime_type": "application/pdf", "size": 52340}], ...}

search()¶

Search emails with automatic FTS5 optimization. Uses the FTS5 index for fast search (~2ms) when available, falls back to JXA-based search otherwise.

Parameters:

Scopes:

Returns: List of results sorted by relevance (FTS5) or date (JXA fallback), each with: id, subject, sender, date_received, score, matched_in, and optionally content_snippet, account, mailbox.

search("invoice")
# Search everywhere — uses FTS5 for instant results

search("john@example.com", scope="sender")
# Find emails from a specific sender

search("meeting notes", scope="body")
# Search body content only

search("pdf", scope="attachments")
# Find emails with PDF attachments

search("deadline", limit=5)
# Top 5 results

search("invoice", after="2025-01-01", before="2025-12-31")
# Emails from 2025 only

search("meeting", highlight=True)
# Results with matching terms highlighted

get_email_links()¶

Extract all links (URLs) from an email's body content.

Parameters:

Returns: List of links found in the email body.

get_email_links(12345)
# → [{"url": "https://example.com/invoice", "text": "View Invoice"}, ...]

get_email_attachment()¶

Extract attachment content from an email. Parses the raw .emlx MIME structure, so it works for all attachment types including inline images.

Parameters:

Returns: Dictionary with filename, mime_type, size, and content_base64. If the attachment exceeds 10 MB, returns metadata only with truncated: true.

get_email_attachment(12345, "invoice.pdf")
# → {"filename": "invoice.pdf", "mime_type": "application/pdf",
#    "size": 52340, "content_base64": "JVBERi0x..."}

get_attachment() (Deprecated)¶

Identical to get_email_attachment(). See above for parameters and return value.