Apple Mail · mgcrea — Claude Code MCP server: what it does, how to install
MCP server connecting macOS Apple Mail to coding agents. It searches local messages and reads email bodies directly on your Mac without external IMAP logins.
claude mcp add --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> --transport stdio mail -- npx -y @mgcrea/mcp-apple-mailWhat Apple Mail does
The server taps into local mailbox files on macOS instead of sending credentials to cloud APIs. Operations follow two routes: AppleScript handles account listings, mailbox tallies and mutations, while message lookups read the local SQLite Envelope Index. Message bodies and attached files are loaded directly from .emlx files on disk.
Two distinct macOS permissions govern operation. Automation grants access to Mail.app events, while Full Disk Access lets the server query the search index and open message files. Without disk access, search fails completely. To avoid giving full disk privileges to your IDE process chain, the author distributes Cupertino (brew install --cask mgcrea/tap/cupertino), a signed utility holding the needed entitlement.
All modifications stay locked under APPLE_MAIL_ALLOW_WRITES="0" unless changed deliberately. As a result, agents cannot delete or transmit messages right after setup. Whenever an operation fails silently, running apple_mail_diagnostics pinpoints the missing permission.
What it helps with
- query local mail threads using SQLite index files
- retrieve message content and attachments from disk
- check mailbox accounts and count unread messages
- draft and send messages through AppleScript when writes are enabled
Example prompts for the agent
- Run
apple_mail_diagnosticsto verify permissions on macOS - List my configured mail accounts and unread message tallies
- Find recent messages from my accounting team and display their subjects
How to install Apple Mail
Platform CLI
claude mcp add --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> --transport stdio mail -- npx -y @mgcrea/mcp-apple-mailReplace <…> with your own values
Platform CLI
codex mcp add mail --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> -- npx -y @mgcrea/mcp-apple-mailReplace <…> with your own values
Config file
{
"mcpServers": {
"mail": {
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-mail"
],
"env": {
"APPLE_MAIL_ALLOW_WRITES": "<APPLE_MAIL_ALLOW_WRITES>",
"APPLE_MAIL_ACCOUNTS": "<APPLE_MAIL_ACCOUNTS>",
"APPLE_MAIL_ALLOW_FILE_SEND": "<APPLE_MAIL_ALLOW_FILE_SEND>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mail": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@mgcrea/mcp-apple-mail"
],
"env": {
"APPLE_MAIL_ALLOW_WRITES": "<APPLE_MAIL_ALLOW_WRITES>",
"APPLE_MAIL_ACCOUNTS": "<APPLE_MAIL_ACCOUNTS>",
"APPLE_MAIL_ALLOW_FILE_SEND": "<APPLE_MAIL_ALLOW_FILE_SEND>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> -e APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> -e APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> mail npx -y @mgcrea/mcp-apple-mailReplace <…> with your own values
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 Apple Mail in Claude Code?
Run claude mcp add mcp-apple-mail -- npx -y @mgcrea/mcp-apple-mail in your terminal. If you need custom write permissions and account filters, execute `claude mcp add --env APPLE_MAIL_ALLOW_WRITES=<APPLE_MAIL_ALLOW_WRITES> --env APPLE_MAIL_ACCOUNTS=<APPLE_MAIL_ACCOUNTS> --env APPLE_MAIL_ALLOW_FILE_SEND=<APPLE_MAIL_ALLOW_FILE_SEND> --transport stdio mail -- npx -y @mgcrea/mcp-apple-mail`.
Why does this server require Full Disk Access?
The server reads Mail's SQLite database and .emlx message files directly from your user library for fast searching. Without Full Disk Access, searching and body inspection fail, leaving only account listings operational.
Can the agent send emails immediately after installation?
No, all writing operations are turned off by default using APPLE_MAIL_ALLOW_WRITES="0". Mutation tools are not registered until you explicitly update this environment setting.
Similar MCP servers
All MCP servers for Notes, tasks and projects →Apple Mail by other authors comes first.
