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.

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).

List all available Mail accounts.

List all configured email addresses for each Mail account.

Useful for mapping a Mail.app account name (e.g. "Gmail", "Work") to the actual email address(es) it receives mail at — handy when an integration needs to know which inbox a message landed in by address rather than by Mail.app's display name.

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

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

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.

Get an email conversation thread - messages linked by Message-ID, not just by subject.

Candidates are found by subject (fast, filtered inside Mail), then linked through their Message-ID / In-Reply-To / References headers. Messages that merely share the subject but belong to a different conversation are listed separately instead of being mixed into the thread.

Return the raw RFC 822 source of a single message.

The MCP's other body-extraction paths return Mail.app's rendered content (HTML collapsed to display text, hrefs dropped, embedded objects replaced with U+FFFC). This tool returns the raw source instead — all headers, all MIME parts, all hrefs intact.

Implementation note:

Wraps the source property of message defined in Mail.sdef (the AppleScript dictionary for Mail.app). That property returns the same RFC 822 text Mail.app writes to the on-disk .partial.emlx file, so the consumer does not need filesystem access or knowledge of the Mail directory layout to recover MIME parts / hrefs / custom headers.

Identifier resolution: message_id is preferred when both are provided (exact match on the RFC 822 Message-Id header via AppleScript's message id property — distinct from id, which is Mail.app's internal numeric id). subject_keyword matches the first message in mailbox whose subject contains the substring.

Output sizing: messages can be large (a plain note is ~200 KB; with attachments far larger). max_bytes caps the returned payload and appends a truncation marker when exceeded. headers_only=True returns only the RFC 822 header block (everything up to and including the first blank line) — usually sufficient for URL/header inspection and avoids returning base64 bodies. Cap applies after the headers_only filter.

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.

Reply to an email matching a subject keyword.

Compose and send a new email from a specific account.

Forward an email to one or more recipients.

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

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". Pass message_ids to move specific messages by exact id (ignores other filters; same fast path as update_email_status).

Save a specific attachment from an email to disk.

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.

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.

Mail's AppleScript interface has no command that erases a message: delete means "move to Trash", and on a message that already sits in Trash it does nothing. "delete_permanent" and "empty_trash" therefore usually remove nothing at all. Both report the real before/after mailbox count instead of the number of delete calls, and say so when nothing was removed; emptying the trash for good has to happen in Mail itself.

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.

Force Mail.app to synchronize an account (or every account) with its IMAP / Exchange server right now. Equivalent to clicking the refresh button next to the account or selecting Mailbox → Synchronize.

Use after move_email, update_email_status, or manage_trash when downstream clients (iPhone, web mail, etc.) need to see the change immediately. Mail.app's natural sync cadence is "automatic" which can be several minutes — this collapses that to one IMAP push.

Implementation note:

Uses the synchronize with <account> AppleScript verb (per Mail.sdef: "Command to trigger synchronizing of an IMAP account with the server") rather than check for new mail. The latter is receive-only — it pulls new messages but does NOT push pending IMAP commands like queued moves / archives / flag changes. With check for new mail, archives done via move_email could sit in Mail.app's local cache for several minutes before reaching the IMAP server, leaving iPhone Mail (which reads IMAP directly) showing already-archived messages still in INBOX. synchronize with is the bidirectional verb that drains pending IMAP commands AND fetches new mail.

Mail.app's synchronize is potentially long-running. We wrap each invocation in with timeout of N seconds so the AppleScript returns promptly. When the timeout fires (error -1712) Mail.app keeps the sync running in the background — exactly the fire-and-forget semantics callers expect.

List attachments for emails matching a subject keyword.

Get comprehensive email statistics and analytics.

Export emails to files for backup or analysis.

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.

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.

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.

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.