Apple Mail MCP Server by sweetrb: Setup for Claude Code, Codex and More

• Finds emails by sender, subject, text, date or status

  Searches across your accounts and returns each match with an id, date, subject, sender, mailbox and read state. The ids are what other tools need.

  Try: “Find unread emails from john@example.com this week.”

  Read · search-messages

• Lists recent emails in a mailbox

  Browses a mailbox page by page, optionally for one sender or unread only, and returns ids with date, subject and sender.

  Try: “Show my 20 latest inbox messages.”

  Read · list-messages

• Reads one email in full

  Returns the subject and body of a message you already have the id for, as plain text or HTML.

  Try: “Read the email from the landlord.”

  Read · get-message

• Shows an email's raw headers

  Returns the technical headers of a message, such as the sender's Date line, Message-ID and the Received trail, without the body.

  Try: “Show the headers of that suspicious email.”

  Read · get-message-headers

• Gets the original email file exactly as stored

  Fetches a message's complete original bytes from the mail server for archiving, with a SHA-256 hash. It works only for accounts set up over IMAP, and can save the result to a file.

  Try: “Save the original of that invoice email to my Documents folder.”

  Files · get-message-rfc822

• Shows a whole conversation

  Gathers the messages in the same conversation as one email, oldest first.

  Try: “Show the full thread for this email.”

  Read · get-thread

• Saves a draft for you to review

  Creates an email in Drafts instead of sending it. The README names this the safe choice for any new message.

  Try: “Draft a reply to the team about Friday's meeting.”

  Write · create-draft

• Sends an email right away

  Sends one email immediately to the recipients you give, with optional attachments. The tool's own description says it cannot be unsent, so confirm recipients and text first.

  Try: “Send Anna the meeting notes.”

  Write · send-email

• Sends personalized copies to a list

  Mail merge: sends one personalized email per recipient, up to 100, with placeholders filled from each recipient's details.

  Try: “Send each client their invoice number in the same message.”

  Write · send-serial-email

• Replies to an email

  Replies to a message by id, keeping the thread and quote. It can reply to everyone, and it can save a draft instead of sending.

  Try: “Reply to John saying Thursday works, as a draft.”

  Write · reply-to-message

• Forwards an email

  Forwards a message by id to new recipients with an optional note. It can save a draft instead of sending.

  Try: “Forward this to my colleague with a short note.”

  Write · forward-message

• Marks one email as read

  Sets one message to read.

  Try: “Mark that email as read.”

  Write · mark-as-read

• Marks one email as unread

  Sets one message back to unread.

  Try: “Mark that email unread so I see it later.”

  Write · mark-as-unread

• Flags one email, with an optional color

  Flags a message, optionally red, orange, yellow, green, blue, purple or gray.

  Try: “Flag the contract email in red.”

  Write · flag-message

• Removes the flag from one email

  Clears the flag on one message.

  Try: “Remove the flag from that email.”

  Write · unflag-message

• Files one email into another folder

  Moves one message into a mailbox you name, for example to archive it.

  Try: “Move this email to Archive.”

  Write · move-message

• Moves one email to the Trash

  Deletes one message by moving it to Trash.

  Try: “Delete that newsletter.”

  Delete · delete-message

• Marks many emails as read

  Sets up to 100 messages to read at once and reports how many worked.

  Try: “Mark all these newsletters as read.”

  Write · batch-mark-as-read

• Marks many emails as unread

  Sets up to 100 messages to unread at once.

  Try: “Mark these three emails as unread.”

  Write · batch-mark-as-unread

• Flags many emails at once

  Flags up to 100 messages, optionally with a color.

  Try: “Flag all the invoices from this month in green.”

  Write · batch-flag-messages

• Unflags many emails at once

  Clears flags on up to 100 messages.

  Try: “Remove flags from all of last year's emails.”

  Write · batch-unflag-messages

• Files many emails into one folder

  Moves up to 100 messages to the same mailbox in one call, for example to bulk archive.

  Try: “Move all these receipts to the Receipts folder.”

  Write · batch-move-messages

• Moves many emails to the Trash

  Moves up to 100 messages to Trash in one call and reports counts of successes and failures.

  Try: “Delete all the promotional emails I just listed.”

  Delete · batch-delete-messages

• Converts an IMAP id to a Mail id

  Looks up the numeric Mail.app id for messages found with an imap: id, which replying and forwarding need.

  Try: “Get the Mail id for that IMAP message.”

  Read · resolve-message-id

• Lists an email's attachments

  Returns each attachment's name, type and size for a message.

  Try: “What attachments does the invoice email have?”

  Read · list-attachments

• Saves an attachment to a folder

  Writes one attachment into a directory you name. The tool only accepts folders inside its allowed roots and rejects path tricks.

  Try: “Save the PDF from that email to my Downloads folder.”

  Write · save-attachment

• Gets an attachment's contents without saving

  Returns up to 3 MiB of an attachment as base64 so the assistant can read it without writing a file.

  Try: “Read the text in the attached CSV.”

  Read · fetch-attachment

• Lists your folders with counts

  Shows the mailboxes in your accounts with their paths and unread and message counts, and says when an account could not be read.

  Try: “List all my mail folders.”

  Read · list-mailboxes

• Counts unread emails

  Returns the number of unread messages for the inbox, or a mailbox or account you name.

  Try: “How many unread emails do I have?”

  Read · get-unread-count

• Creates a mail folder

  Creates a new mailbox in an account.

  Try: “Create a folder called Receipts 2026.”

  Write · create-mailbox

• Renames a mail folder

  Renames an existing mailbox within an account.

  Try: “Rename the folder Old to Archive 2024.”

  Write · rename-mailbox

• Deletes a mail folder

  Deletes a folder. The tool's description says this removes the folder and any messages it contains.

  Try: “Delete the empty folder Temp.”

  Delete · delete-mailbox

• Lists your smart mailboxes

  Shows smart mailboxes and a summary of their criteria. It works on German-language macOS too.

  Try: “What smart mailboxes do I have?”

  Read · list-smart-mailboxes

• Creates a smart mailbox

  Creates a smart mailbox that matches a sender, subject or body text.

  Try: “Create a smart mailbox for emails from my bank.”

  Write · create-smart-mailbox

• Deletes a smart mailbox

  Removes a smart mailbox by name. Only the saved search goes, not real folders or messages.

  Try: “Delete my smart mailbox "Bank".”

  Delete · delete-smart-mailbox

• Finds newsletter senders and makes a smart mailbox for each

  Scans up to about 400 recent messages per inbox to find bulk senders. It only proposes by default, and with dry run off it edits Apple Mail's smart mailbox file (backed up first) and can create many at once.

  Try: “Show me which newsletters I could group into smart mailboxes.”

  Write · create-newsletter-smart-mailboxes

• Lists your mail accounts

  Returns the names of the accounts set up in Mail, such as iCloud or Gmail, to pass to other tools.

  Try: “Which mail accounts do I have?”

  Read · list-accounts

• Lists your mail rules

  Shows each Mail rule and whether it is on.

  Try: “What mail rules do I have?”

  Read · list-rules

• Turns a mail rule on

  Enables an existing rule by name.

  Try: “Turn on my "Receipts" rule.”

  Write · enable-rule

• Turns a mail rule off

  Disables a rule by name without deleting it.

  Try: “Pause my newsletter rule.”

  Write · disable-rule

• Creates a mail rule

  Adds a rule with conditions and actions such as mark read, flag, move or delete. It then acts on your real mail on an ongoing basis.

  Try: “Create a rule that files mail from billing@example.com into Receipts.”

  Delete · create-rule

• Deletes a mail rule

  Removes a rule permanently by name.

  Try: “Delete my "Old promos" rule.”

  Delete · delete-rule

• Looks up people in your Contacts

  Searches the macOS Contacts database for names, emails and phone numbers. It needs Full Disk Access and Node.js 22.5 or later.

  Try: “What is Maria's email address?”

  Files · search-contacts

• Saves a reusable email template

  Stores a template with subject, body and optional default recipients in a file on your Mac. Using an existing id overwrites that template.

  Try: “Save this as a template called "Weekly update".”

  Write · save-template

• Lists your saved templates

  Returns the id, name and subject of each saved template.

  Try: “What email templates do I have?”

  Read · list-templates

• Shows one template

  Returns a template's full subject, recipients and body.

  Try: “Show my "Weekly update" template.”

  Read · get-template

• Deletes a saved template

  Removes a saved template permanently by id.

  Try: “Delete the "Weekly update" template.”

  Delete · delete-template

• Makes a draft from a template

  Creates a draft in Mail from a saved template, with any changes you ask for, for you to review and send.

  Try: “Draft an email from my "Weekly update" template for the team.”

  Write · use-template

• Checks that Mail is reachable

  Runs a quick pass or fail check of the connection to Mail.app.

  Try: “Is the Mail connection working?”

  Read · health-check

• Diagnoses setup problems

  Checks Mail permissions, accounts and the IMAP and SMTP setup and explains how to fix what is wrong.

  Try: “Run the doctor and tell me why sending fails.”

  Read · doctor

• Shows mailbox totals

  Returns total and unread counts, recent arrivals over the last 24 hours, 7 days and 30 days, and a per-account breakdown.

  Try: “How much mail did I get this week?”

  Read · get-mail-stats

• Checks if Mail is syncing

  Reports whether Mail.app is running and syncing, which explains why new mail may not show yet.

  Try: “Is Mail still syncing?”

  Read · get-sync-status

Watch out for

• It sends real email that cannot be unsent

  The send, reply, forward and mail-merge tools send straight away unless you ask for a draft. Ask for drafts and read them before sending. github.com

• It can delete messages, folders and rules

  It can delete messages (to Trash, up to 100 at once), whole mailboxes with their messages, mail rules and smart mailboxes. Confirm the exact names before each delete. github.com

• A mail rule keeps acting on your mail

  The rule tool can create rules that mark, move or delete mail on an ongoing basis. Review the conditions before you allow it. github.com

• Attachments and templates write files on your Mac

  Saving an attachment writes into a folder you name inside its allowed roots, and templates are stored in a file under Application Support. Outbound attachments may come from ordinary files under your home folder, with credential and config locations denied by default. github.com

• Contact search needs Full Disk Access

  Searching contacts reads the Contacts database directly, so it needs Full Disk Access for Node and Node.js 22.5 or later. Skip that permission if you do not need it. github.com

Security advisories