Apple Mail MCP — Claude Code MCP server: search your mail
An MCP server for reading and searching Apple Mail. Body search runs over an FTS5 index that covers the whole mailbox, not just recent messages.
claude mcp add apple-mail-mcp -- uvx apple-mail-mcpWhat Apple Mail MCP does
The server exposes 8 tools to your agent: list accounts and mailboxes, fetch emails by filter, read one message with attachments, search subject, sender, body and attachments, pull links and attachment contents. Body search goes through an FTS5 index, so old messages turn up too.
Install it like any MCP server: pipx install apple-mail-mcp, then point your client at the apple-mail-mcp command. Claude users can take the plugin from the marketplace, which runs the same PyPI package through a thin launcher. Build the index afterwards with apple-mail-mcp index --verbose.
It needs macOS and Python 3.11+. The terminal or app that launches the server has to have Full Disk Access, otherwise the index will not refresh. Every tool also works as a standalone CLI command with JSON output.
What it helps with
- find a message by a phrase in the body, not just the subject
- pull an attachment out of a specific email
- list unread mail from the past week
- extract every link from a message
- switch between several mail accounts
Example prompts for the agent
- Search my mail for messages containing “contract” in the body from last month
- Show unread emails in the Work mailbox
- Extract the invoice.pdf attachment from message 12345
How to install Apple Mail MCP
Platform CLI
claude mcp add apple-mail-mcp -- uvx apple-mail-mcpuvx runs the command named after the package; if the README names another one, use uvx --from apple-mail-mcp <command>
Platform CLI
codex mcp add apple-mail-mcp -- uvx apple-mail-mcpuvx runs the command named after the package; if the README names another one, use uvx --from apple-mail-mcp <command>
Config file
{
"mcpServers": {
"apple-mail-mcp": {
"command": "uvx",
"args": [
"apple-mail-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from apple-mail-mcp <command>
Config file
{
"servers": {
"apple-mail-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"apple-mail-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from apple-mail-mcp <command>
Platform CLI
gemini mcp add apple-mail-mcp uvx apple-mail-mcpuvx runs the command named after the package; if the README names another one, use uvx --from apple-mail-mcp <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 MCP
How do I install Apple Mail MCP in Claude Code?
Through the plugin marketplace: claude plugin marketplace add imdinu/apple-mail-mcp, then claude plugin install apple-mail@imdinu. Or add it as an MCP server with claude mcp add apple-mail-mcp -- uvx apple-mail-mcp.
What does Apple Mail MCP do?
It gives an agent access to Apple Mail: list accounts and mailboxes, read messages, search subject, sender, body and attachments, extract links and files. Body search runs over an FTS5 index covering the whole mailbox.
What does the server need to run?
macOS, Python 3.11+ and Full Disk Access for the app that launches the server. Build the index with apple-mail-mcp index --verbose after installing.
