Apple Mail MCP

MCP server for Apple Mail on macOS.

Provides access to mailboxes, message search, reading, and composition. Keep Mail as the system of record while enabling agents to search, read, draft, and send email.

When to use

• Mail-only workflows
• Tighter permissions than the all-in-one server
• Draft and send workflows through the native Mail app

What It Does

• List mailboxes
• Search and read messages
• Create drafts and send messages
• Reply, forward, mark read/unread, move, and delete
• Tool discovery helpers search_tools and get_tool_info for context-constrained clients
• Thread helpers: mail_get_thread, mail_reply_latest_in_thread, mail_archive_thread
• Mailbox resources and reply-oriented prompts
• Health and permission checks: mail_health, mail_permission_guide, mail_recheck_permissions

Tools

mail_health, mail_permission_guide, mail_recheck_permissions, mail_list_mailboxes, mail_search_messages, mail_get_message, mail_get_thread, mail_compose_draft, mail_send_message, mail_reply_message, mail_forward_message, mail_mark_message, mail_move_message, mail_delete_message, mail_reply_latest_in_thread, mail_archive_thread, mail_list_prompts, mail_get_prompt, plus the discovery helpers search_tools and get_tool_info.

Install On This Mac

uvx apple-mcp-mail

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

Install In AI Agents

{
  "mcpServers": {
    "apple-mail": {
      "command": "uvx",
      "args": ["apple-mcp-mail"],
      "env": {
        "APPLE_MAIL_MCP_SAFETY_PROFILE": "safe_manage",
        "APPLE_MAIL_MCP_VISIBLE_DRAFTS": "true"
      }
    }
  }
}

claude mcp add --transport stdio --scope project apple-mail -- uvx apple-mcp-mail

Safety Modes

• safe_readonly, read and search only
• safe_manage, read, create drafts, reply/forward, mark, move, delete, and archive threads; new-message sending is blocked
• full_access, full Mail tool surface in this repo, including new-message sending

These are the existing policy rules. Deleting or archiving does not require switching from safe_manage to full_access.

Transport

stdio is the default and recommended transport. Set APPLE_MAIL_MCP_TRANSPORT=streamable-http (with optional APPLE_MAIL_MCP_HOST and APPLE_MAIL_MCP_PORT) to serve Streamable HTTP instead.

macOS Permissions

• Automation access to Mail is required

Troubleshooting move/delete errors

Issue #23 reports AppleScript -1728 errors containing item ... of every message/mailbox/account. The move and delete scripts now resolve account/mailbox matches into concrete objects and look up messages by Mail's numeric ID within the original mailbox, instead of retaining positional repeat-loop references. They refuse missing or ambiguous targets and do not automatically retry mutations.

Use message_id exactly as returned by mail_search_messages. If the message has moved or the ID no longer resolves in its original mailbox, search again rather than editing the ID. ACCOUNT_AMBIGUOUS, MAILBOX_AMBIGUOUS, and their TARGET_ counterparts mean the configured names do not uniquely identify the requested object; make the selection unambiguous before retrying. Other native errors, including permission errors, remain visible.

For archiving, call mail_list_mailboxes and pass the actual destination name. Do not assume the account exposes a mailbox literally named Archive, particularly with localized or nested Gmail labels. Keep the intended account explicit when moving between accounts.

A successful mail_health response does not verify a move/delete round trip. Validate a new installation using disposable messages with unique subjects: search, perform one requested operation, and confirm the outcome in Mail. Thread archiving moves messages individually and is not transactional; after an error, inspect Mail before retrying the whole thread.

Restart the MCP client after upgrading. A fix merged on GitHub is not available to uvx installations from PyPI until a package release includes it. A source checkout can be tested through the clone instructions above; use Apple-Tools-MCP/start.sh for the unified server. If an error persists, report the installed version or source commit, macOS version, operation, and redacted error text. Do not post message bodies or private account details.

Launch Checklist

• Add uvx apple-mcp-mail (or a clone's AppleMail-MCP/start.sh) to your MCP client
• Reload or reconnect the client so the Mail tool surface is loaded into context
• Call mail_health first to confirm the server is reachable
• If Mail automation is blocked, call mail_permission_guide
• After changing macOS permissions, call mail_recheck_permissions

Prompting Notes

• Run Contacts before any send or reply when the user identifies a person rather than an email address.
• tools/list returns the full Mail tool surface. Context-constrained clients can call search_tools first, then get_tool_info for the exact Mail tool they plan to call.
• mail_search_messages requires a query string. Use a sender, a subject fragment, or * as a wildcard.
• There is no list-all recent-mail endpoint.
• Use mail_get_thread when the user means a conversation, not a single message.
• Use mail_reply_latest_in_thread when the agent should reply to the newest message in the conversation.
• Use mail_archive_thread when the user wants thread-level cleanup and Archive is the intended mailbox.
• If the user could mean text or email, ask once before choosing Messages or Mail.
• When Mail must send from a specific identity, pass the exact sender email in from_account.

Related

• Apple-Tools-MCP

Attachment access

File attachments are disabled until you set APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT to a directory you choose, such as ~/Documents/Mail Attachments. This applies to both drafts and sends, including calls through Apple Tools. The server resolves symlinks and accepts only regular files inside that directory. Files outside it, directories, and paths containing the attachment transport separator are rejected. Mail operations without attachments continue to work with the existing safety profile.