Apple Mail — macOS MCP server for Claude Code: setup
Lets your coding agent read, search, draft and send mail through Apple Mail on macOS, without leaving the chat.
claude mcp add --env APPLE_MAIL_MCP_SAFETY_PROFILE=<APPLE_MAIL_MCP_SAFETY_PROFILE> --env APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT=<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT> --env APPLE_MAIL_MCP_VISIBLE_DRAFTS=<APPLE_MAIL_MCP_VISIBLE_DRAFTS> --transport stdio applemail-mcp -- uvx apple-mcp-mailWhat Apple Mail does
The server runs locally on your Mac and exposes mail tools to the client: search by sender or subject fragment, read conversations, prepare drafts, send. Thread work has its own helpers — mail_get_thread, mail_reply_latest_in_thread, mail_archive_thread. Resolve recipients through Contacts first when you do not have the exact address.
macOS and Python 3.11+ are required, and uv has to be installed before uvx can pull the package. Safety behaviour comes from APPLE_MAIL_MCP_SAFETY_PROFILE: safe_manage under uvx and pip, full_access in the Claude Desktop bundles. A blank or invalid value drops the server into safe_readonly, so writes stop working. Attachments stay off until APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT points at a folder set aside for them.
Nothing keeps the data on your machine by itself. Your client may forward what it gets to its model provider, and Apple apps sync through iCloud or whatever account is signed in. stdio is the default transport. Streamable HTTP binds only to 127.0.0.1, ::1 or localhost — there is no remote authentication, so a tunnel or public proxy is off the table. You approve the macOS permissions yourself, in the system prompt or System Settings.
What it helps with
- find a message by sender or a fragment of the subject
- read a whole thread and reply to its latest message
- send from a specific address via
from_account - archive a thread once it is handled
- check Mail access without reading any messages
Example prompts for the agent
- Search Apple Mail for messages from the finance team this week
- Open the thread about the contract and reply to the last message
- Send the draft from
[email protected]
How to install Apple Mail
Platform CLI
claude mcp add --env APPLE_MAIL_MCP_SAFETY_PROFILE=<APPLE_MAIL_MCP_SAFETY_PROFILE> --env APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT=<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT> --env APPLE_MAIL_MCP_VISIBLE_DRAFTS=<APPLE_MAIL_MCP_VISIBLE_DRAFTS> --transport stdio applemail-mcp -- uvx apple-mcp-mailReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-mcp-mail <command>
Platform CLI
codex mcp add applemail-mcp --env APPLE_MAIL_MCP_SAFETY_PROFILE=<APPLE_MAIL_MCP_SAFETY_PROFILE> --env APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT=<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT> --env APPLE_MAIL_MCP_VISIBLE_DRAFTS=<APPLE_MAIL_MCP_VISIBLE_DRAFTS> -- uvx apple-mcp-mailReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-mcp-mail <command>
Config file
{
"mcpServers": {
"applemail-mcp": {
"command": "uvx",
"args": [
"apple-mcp-mail"
],
"env": {
"APPLE_MAIL_MCP_SAFETY_PROFILE": "<APPLE_MAIL_MCP_SAFETY_PROFILE>",
"APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT": "<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT>",
"APPLE_MAIL_MCP_VISIBLE_DRAFTS": "<APPLE_MAIL_MCP_VISIBLE_DRAFTS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-mcp-mail <command>
Config file
{
"servers": {
"applemail-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"apple-mcp-mail"
],
"env": {
"APPLE_MAIL_MCP_SAFETY_PROFILE": "<APPLE_MAIL_MCP_SAFETY_PROFILE>",
"APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT": "<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT>",
"APPLE_MAIL_MCP_VISIBLE_DRAFTS": "<APPLE_MAIL_MCP_VISIBLE_DRAFTS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-mcp-mail <command>
Platform CLI
gemini mcp add -e APPLE_MAIL_MCP_SAFETY_PROFILE=<APPLE_MAIL_MCP_SAFETY_PROFILE> -e APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT=<APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT> -e APPLE_MAIL_MCP_VISIBLE_DRAFTS=<APPLE_MAIL_MCP_VISIBLE_DRAFTS> applemail-mcp uvx apple-mcp-mailReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from apple-mcp-mail <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Apple Mail
How do I install the Apple Mail MCP server in Claude Code?
Install uv first, then run claude mcp add apple-mcp-mail -- uvx apple-mcp-mail. Restart the client afterwards.
What does the Apple Mail MCP server do?
It gives an agent read, search, draft and send access to Apple Mail on macOS, plus helpers for threads and attachments.
Why do some tools refuse to run?
Check the safety profile. A blank or invalid APPLE_MAIL_MCP_SAFETY_PROFILE selects safe_readonly, which blocks anything that writes.
