Apple Mail MCP Server

List all emails from inbox across all accounts or a specific account.

Replaces the former get_recent_emails tool — use account + max_emails to get recent emails from a single account.

Args: account: Optional account name to filter (e.g., "Gmail", "Work"). If None, shows all accounts. max_emails: Maximum number of emails to return per account (0 = all) include_read: Whether to include read emails (default: True) include_content: Whether to include a content preview for each email (slower, default: False) output_format: "text" (default, human-readable) or "json" (structured list of email dicts)

Returns: Formatted list of emails with subject, sender, date, and read status

Get unread counts per mailbox for one account or all accounts.

When summary_only=True, returns only per-account inbox unread totals (replaces the former get_unread_count tool).

Args: account: Optional account name filter include_zero: Whether to include mailboxes with zero unread messages summary_only: If True, return only per-account inbox unread totals (flat dict of account name -> unread count)

Returns: If summary_only=False: nested dict keyed by account name then mailbox path If summary_only=True: flat dict mapping account names to inbox unread counts

List all available Mail accounts.

Returns: List of account names

List all mailboxes (folders) for a specific account or all accounts.

Args: account: Optional account name to filter (e.g., "Gmail", "Work"). If None, shows all accounts. include_counts: Whether to include message counts for each mailbox (default: True)

Returns: Formatted list of mailboxes with optional message counts. For nested mailboxes, shows both indented format and path format (e.g., "Projects/Amplify Impact")

Get a comprehensive overview of your email inbox status across all accounts.

Returns: Comprehensive overview including: - Unread email counts by account - List of available mailboxes/folders - AI suggestions for actions (move emails, respond to messages, highlight action items, etc.)

This tool is designed to give you a complete picture of your inbox and prompt the assistant to suggest relevant actions based on the current state.

Unified search tool with JSON output, pagination, and real date filtering.

Consolidates subject search, sender search, body content search, and cross-account search into a single tool.

Args: account: Account name to search in (e.g., "Gmail", "Work"). If None, searches ALL accounts (slower). mailbox: Mailbox to search (default: "INBOX", use "All" for all mailboxes, or specific folder name) subject_keyword: Optional keyword to search in subject subject_keywords: Optional list of subject keywords; matches any keyword sender: Optional sender email or name to filter by has_attachments: Optional filter for emails with attachments (True/False/None) read_status: Filter by read status: "all", "read", "unread" (default: "all") date_from: Optional start date filter (format: "YYYY-MM-DD") date_to: Optional end date filter (format: "YYYY-MM-DD") include_content: Whether to include email content preview (slower) max_content_length: Maximum content length in characters when include_content=True (default: 500, 0 = unlimited) body_text: Optional text to search for in email body content (case-insensitive). WARNING: body search is significantly slower as it reads each message body. max_results: Backward-compatible alias for limit output_format: Output format: "text" or "json" (default: "text") offset: Number of matching results to skip before returning data limit: Maximum number of results to return per page sort: Result sort order: "date_desc" or "date_asc"

Returns: Formatted list of matching emails or JSON payload with stable message metadata

Get an email conversation thread - all messages with the same or similar subject.

Args: account: Account name (e.g., "Gmail", "Work") subject_keyword: Keyword to identify the thread (e.g., "Re: Project Update") mailbox: Mailbox to search in (default: "INBOX", use "All" for all mailboxes) max_messages: Maximum number of thread messages to return (default: 50)

Returns: Formatted thread view with all related messages sorted by date

Create a rich-text email draft by generating an unsent .eml message and optionally opening it in Mail.

This is the preferred path for HTML or richly formatted emails because Mail reliably renders .eml content, while setting raw HTML through AppleScript often stores the literal markup instead.

Args: account: Account name to use for the sender identity (e.g., "Work", "Oracle") subject: Subject line for the draft (optional; defaults to empty) to: Optional recipient email address(es), comma-separated for multiple text_body: Optional plain-text body. If omitted but html_body is provided, a fallback plain body is generated. html_body: Optional HTML body. If omitted but text_body is provided, a basic HTML wrapper is generated. cc: Optional CC recipients, comma-separated for multiple bcc: Optional BCC recipients, comma-separated for multiple output_path: Optional path for the generated .eml file open_in_mail: If True, open the generated .eml in Mail (default: True) save_as_draft: If True, ask Mail to save the opened compose window into Drafts (default: False)

Returns: Confirmation with the generated .eml path, missing details, and Mail-open/save status

Reply to an email matching a subject keyword.

Args: account: Account name (e.g., "Gmail", "Work") subject_keyword: Keyword to search for in email subjects reply_body: The body text of the reply reply_to_all: If True, reply to all recipients; if False, reply only to sender (default: False) cc: Optional CC recipients, comma-separated for multiple bcc: Optional BCC recipients, comma-separated for multiple send: If True (default), send immediately; if False, save as draft. Ignored if mode is set. mode: Delivery mode — "send" (send immediately), "draft" (save silently), or "open" (open compose window for review). Overrides send parameter when set. attachments: Optional file paths to attach, comma-separated for multiple (e.g., "/path/to/file1.png,/path/to/file2.pdf") body_html: Optional HTML body for rich formatting (bold, headings, links, colors). When provided, the reply is pasted as HTML. The plain 'reply_body' field is still required as fallback text.

Returns: Confirmation message with details of the reply sent, saved draft, or opened draft

Compose and send a new email from a specific account.

Args: account: Account name to send from (e.g., "Gmail", "Work", "Personal") to: Recipient email address(es), comma-separated for multiple subject: Email subject line body: Email body text (used as plain-text fallback when body_html is provided) cc: Optional CC recipients, comma-separated for multiple bcc: Optional BCC recipients, comma-separated for multiple attachments: Optional file paths to attach, comma-separated for multiple (e.g., "/path/to/file1.png,/path/to/file2.pdf") mode: Delivery mode — "send" (send immediately, default), "draft" (save silently to Drafts), or "open" (open compose window for review before sending) body_html: Optional HTML body for rich formatting (bold, headings, links, colors). When provided, the email is sent as HTML. The plain 'body' field is still required as fallback text.

Returns: Confirmation message with details of the email

Forward an email to one or more recipients.

Args: account: Account name (e.g., "Gmail", "Work") subject_keyword: Keyword to search for in email subjects to: Recipient email address(es), comma-separated for multiple message: Optional message to add before forwarded content mailbox: Mailbox to search in (default: "INBOX") cc: Optional CC recipients, comma-separated for multiple bcc: Optional BCC recipients, comma-separated for multiple

Returns: Confirmation message with details of forwarded email

Manage draft emails - list, create, send, open, or delete drafts.

Args: account: Account name (e.g., "Gmail", "Work") action: Action to perform: "list", "create", "send", "open", "delete". Use "open" to open a draft in a visible compose window for review before sending. subject: Email subject (required for create) to: Recipient email(s) for create (comma-separated) body: Email body (required for create) cc: Optional CC recipients for create bcc: Optional BCC recipients for create draft_subject: Subject keyword to find draft (required for send/open/delete)

Returns: Formatted output based on action

Move email(s) matching filters from one mailbox to another.

Supports subject, sender, and date filters. Use dry_run=True to preview matches without moving. Set only_read=True to skip unread emails (useful for archiving). For archiving to "Archive", just set to_mailbox="Archive".

Args: account: Account name (e.g., "Gmail", "Work") to_mailbox: Destination mailbox name. For nested mailboxes, use "/" separator (e.g., "Projects/Amplify Impact") subject_keyword: Optional keyword to search for in email subjects from_mailbox: Source mailbox name (default: "INBOX") max_moves: Maximum number of emails to move (default: 50, safety limit) subject_keywords: Optional list of keywords to match in subjects; matches any keyword sender: Optional sender to filter emails by older_than_days: Optional age filter - only move emails older than N days dry_run: If True, preview what would be moved without acting (default: False) only_read: If True, only move emails that have been read (default: False)

Returns: Confirmation message with details of moved emails

Save a specific attachment from an email to disk.

Args: account: Account name (e.g., "Gmail", "Work", "Personal") subject_keyword: Keyword to search for in email subjects attachment_name: Name of the attachment to save save_path: Full path where to save the attachment

Returns: Confirmation message with save location

Update email status - mark as read/unread or flag/unflag emails.

When message_ids is provided, uses exact ID matching (ignores other filters). Otherwise filters by subject, sender, and/or age.

Args: account: Account name (e.g., "Gmail", "Work") action: Action to perform: "mark_read", "mark_unread", "flag", "unflag" subject_keyword: Optional keyword to filter emails by subject subject_keywords: Optional list of subject keywords; matches any keyword sender: Optional sender to filter emails by mailbox: Mailbox to search in (default: "INBOX") max_updates: Maximum number of emails to update (safety limit, default: 10) apply_to_all: Must be True to allow updates without any filter message_ids: Optional list of exact Mail message ids for precise targeting older_than_days: Optional age filter - only update emails older than N days

Returns: Confirmation message with details of updated emails

Manage trash operations - delete emails or empty trash.

When dry_run=True (default) and action is "move_to_trash", previews what would be deleted without acting. Set dry_run=False to actually move to trash.

Args: account: Account name (e.g., "Gmail", "Work") action: Action to perform: "move_to_trash", "delete_permanent", "empty_trash" subject_keyword: Optional keyword to filter emails (not used for empty_trash) subject_keywords: Optional list of subject keywords; matches any keyword sender: Optional sender to filter emails (not used for empty_trash) mailbox: Source mailbox (default: "INBOX", not used for empty_trash or delete_permanent) max_deletes: Maximum number of emails to delete (safety limit, default: 5) confirm_empty: Must be True to execute "empty_trash" action (safety confirmation) apply_to_all: Must be True to allow operations without subject_keyword or sender filter older_than_days: Optional age filter - only affect emails older than N days dry_run: If True (default), preview what would be affected without acting

Returns: Confirmation message with details of deleted emails

Create a new mailbox (folder) in the specified account.

Supports nested paths via the parent_mailbox parameter (e.g., parent_mailbox="Projects" + name="2024" creates Projects/2024). You can also pass a full slash-separated path as name (e.g., "Projects/2024/ClientName") and omit parent_mailbox.

Args: account: Account name (e.g., "Gmail", "Work") name: Name for the new mailbox. May contain "/" to create a nested path in one call (each segment is created if needed). parent_mailbox: Optional existing parent folder for nesting.

Returns: Confirmation with the new mailbox path.

List attachments for emails matching a subject keyword.

Args: account: Account name (e.g., "Gmail", "Work", "Personal") subject_keyword: Keyword to search for in email subjects max_results: Maximum number of matching emails to check (default: 1)

Returns: List of attachments with their names and sizes

Get comprehensive email statistics and analytics.

Args: account: Account name (e.g., "Gmail", "Work") scope: Analysis scope: "account_overview", "sender_stats", "mailbox_breakdown" sender: Specific sender for "sender_stats" scope mailbox: Specific mailbox for "mailbox_breakdown" scope days_back: Number of days to analyze (default: 30, 0 = all time)

Returns: Formatted statistics report with metrics and insights

Export emails to files for backup or analysis.

Args: account: Account name (e.g., "Gmail", "Work") scope: Export scope: "single_email" (requires subject_keyword) or "entire_mailbox" subject_keyword: Keyword to find email (required for single_email) mailbox: Mailbox to export from (default: "INBOX") save_directory: Directory to save exports (default: "~/Desktop") format: Export format: "txt", "html" (default: "txt") max_emails: Maximum number of emails to export for entire_mailbox (default: 1000, safety cap)

Returns: Confirmation message with export location

Get an interactive dashboard view of your email inbox.

Returns an interactive UI dashboard resource that displays:

• Unread email counts by account (visual cards with badges)

• Recent emails across all accounts (filterable list)

• Quick action buttons for common operations (Mark Read, Archive, Delete)

• Search functionality to filter emails

This tool returns a UIResource that can be rendered by compatible MCP clients (like Claude Desktop with MCP Apps support) to provide an interactive dashboard experience.

Note: Requires mcp-ui-server package and a compatible MCP client.

Returns: UIResource with uri "ui://apple-mail/inbox-dashboard" containing an interactive HTML dashboard, or error message if UI is unavailable.

Find sent emails that haven't received a reply yet.

Scans the Sent mailbox for outgoing emails and cross-references with the Inbox to see if a reply (matching subject) was received from the same recipient. Useful for follow-up tracking.

Args: account: Account name (e.g., "Gmail", "Work", "Personal") days_back: How many days back to check sent emails (default: 7) exclude_noreply: Skip emails sent to noreply/no-reply addresses (default: True) max_results: Maximum results to return (default: 20)

Returns: List of sent emails still awaiting a reply with subject, recipient, and date sent

Identify unread emails that likely need a response from you.

Filters out newsletters, automated emails, and noreply senders. Prioritises direct emails (To: you) with question marks as likely needing a reply.

Args: account: Account name (e.g., "Gmail", "Work", "Personal") mailbox: Mailbox to scan (default: "INBOX") days_back: How many days back to look (default: 7) max_results: Maximum results to return (default: 20)

Returns: Ranked list of emails likely needing a response, with priority hints

Analyse a mailbox to find the most frequent senders.

Useful for identifying key contacts, high-volume senders to filter, or newsletter sources to unsubscribe from.

Args: account: Account name (e.g., "Gmail", "Work", "Personal") mailbox: Mailbox to analyse (default: "INBOX") days_back: How many days back to look (default: 30, 0 = all time) top_n: Number of top senders to return (default: 10) group_by_domain: Group results by domain instead of individual sender (default: False)

Returns: Ranked list of senders (or domains) with email counts