Apple Mail MCP Server
Star History
An MCP server that gives AI assistants full access to Apple Mail -- read, search, compose, organize, and analyze emails via natural language. Built with FastMCP.
Quick Install
Prerequisites: macOS with Apple Mail configured, Python 3.10+
Claude Code Plugin (Recommended)
Two commands — gets you the MCP server, /email-management slash command, and the Email Management Expert skill:
claude plugin marketplace add patrickfreyer/apple-mail-mcp
claude plugin install apple-mail@apple-mail-mcp
Then restart Claude Code.
Other Install Methods
uvx (zero install, MCP server only)
claude mcp add apple-mail -- uvx mcp-apple-mail
Or for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"apple-mail": {
"command": "uvx",
"args": ["mcp-apple-mail"]
}
}
}
pip install (MCP server only)
pip install mcp-apple-mail
claude mcp add apple-mail -- mcp-apple-mail
Claude Desktop MCPB
- Download
apple-mail-mcp-v2.2.0.mcpbfrom Releases - Open Claude Desktop → Settings → Developer → MCP Servers → Install from file
- Select the
.mcpbfile and grant Mail.app permissions
Manual setup
git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp/plugin
python3 -m venv venv
venv/bin/pip install -r requirements.txt
claude mcp add apple-mail -- /bin/bash $(pwd)/start_mcp.sh
Tools (22)
Reading & Search
| Tool | Description |
|---|---|
get_inbox_overview | Dashboard with unread counts, folders, and recent emails |
list_inbox_emails | List emails with account/read-status filtering and optional content preview |
get_mailbox_unread_counts | Unread counts per mailbox or per-account summary |
list_accounts | List all configured Mail accounts |
search_emails | Unified search — subject, sender, body text, dates, attachments, cross-account |
get_email_thread | Conversation thread view |
Organization
| Tool | Description |
|---|---|
list_mailboxes | Folder hierarchy with message counts |
create_mailbox | Create new mailboxes (supports nested paths) |
move_email | Move/archive emails with filters (subject, sender, date, read status, dry-run) |
update_email_status | Mark read/unread, flag/unflag — by filters or message IDs |
manage_trash | Soft delete, permanent delete, empty trash (with dry-run) |
Composition
| Tool | Description |
|---|---|
compose_email | Send new emails (plain text or HTML body) |
reply_to_email | Reply or reply-all with optional HTML body |
forward_email | Forward with optional message, CC/BCC |
manage_drafts | Create, list, send, and delete drafts |
create_rich_email_draft | Build a rich HTML .eml draft, open it in Mail, and optionally save it to Drafts |
Attachments
| Tool | Description |
|---|---|
list_email_attachments | List attachments with names and sizes |
save_email_attachment | Save attachments to disk |
Smart Inbox
| Tool | Description |
|---|---|
get_awaiting_reply | Find sent emails that haven't received a reply |
get_needs_response | Identify emails that likely need your response |
get_top_senders | Analyse most frequent senders by count or domain |