Apple Mail MCP Server
A Model Context Protocol (MCP) server that enables AI assistants like Claude to read, send, search, and manage emails in Apple Mail on macOS.
Note: This is the npm/Node.js package — install with npx or npm. There is an unrelated Python project of the same name on PyPI (imdinu/apple-mail-mcp) installed via pipx/uvx. If you're using uvx and seeing a cyclopts dependency error, you're looking for that project, not this one.
What is This?
This server acts as a bridge between AI assistants and Apple Mail. Once configured, you can ask Claude (or any MCP-compatible AI) to:
- "Check my inbox for unread messages"
- "Find emails from john@example.com"
- "Send an email to the team about the meeting"
- "Create a draft email for me to review"
- "Reply to that message"
- "Forward this to my colleague"
- "Move old newsletters to the Archive folder"
The AI assistant communicates with this server, which then uses AppleScript to interact with the Mail app on your Mac. All data stays local on your machine.
Quick Start
Using Claude Code (Easiest)
If you're using Claude Code (in Terminal or VS Code), just ask Claude to install it:
Install the sweetrb/apple-mail-mcp MCP server so you can help me manage my Apple Mail
Claude will handle the installation and configuration automatically.
Using the Plugin Marketplace
Install as a Claude Code plugin for automatic configuration and enhanced AI behavior:
/plugin marketplace add sweetrb/apple-mail-mcp
/plugin install apple-mail
This method also installs a skill that teaches Claude when and how to use Apple Mail effectively.
Manual Installation
1. Install the server:
npm install -g github:sweetrb/apple-mail-mcp
2. Add to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"apple-mail": {
"command": "npx",
"args": ["apple-mail-mcp"]
}
}
}
3. Restart Claude Desktop and start using natural language:
"Show me my unread emails"
On first use, macOS will ask for permission to automate Mail.app. Click "OK" to allow.
Requirements
- macOS - Apple Mail and AppleScript are macOS-only
- Node.js 20+ - Required for the MCP server
- Apple Mail - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)
Features
Messages
| Feature | Description |
|---|
| List Messages | List messages with pagination, sender filter, date display |
| Search Messages | Search by sender, subject, content, date range, read/flagged status — across all accounts |
| Read Messages | Get full email content (plain text or HTML) |
| Send Email | Compose and send new emails (with optional file attachments) |
| Send Serial Email | Mail merge — send personalized emails to a list of recipients with {{placeholder}} support |
| Create Draft | Save emails to Drafts folder (with optional file attachments) |
| Reply | Reply to messages (with reply-all support) |
| Forward | Forward messages to new recipients |
| Mark Read/Unread | Change read status (single or batch) |
| Flag/Unflag | Flag or unflag messages (single or batch) |
| Delete Messages | Move messages to trash (single or batch) |
| Move Messages | Organize into mailboxes (single or batch) |
| List Attachments | View attachment metadata (name, type, size) |
| Save Attachment | Save attachments to disk |
Mailbox & Account Management
| Feature | Description |
|---|
| List Mailboxes | Show all folders with message/unread counts |
| Create/Delete/Rename Mailbox | Full mailbox lifecycle management |
| List Accounts | Show configured accounts |
| Unread Count | Get unread counts per mailbox |
Rules, Contacts & Templates
| Feature | Description |
|---|
| List Rules | View all mail rules and their enabled status |
| Enable/Disable Rules | Toggle mail rules on or off |
| Search Contacts | Look up contacts from Contacts.app by name |
| Email Templates | Save, list, use, and delete reusable email templates |
Diagnostics
| Feature | Description |
|---|
| Health Check | Verify Mail.app connectivity |
| Statistics | Message and unread counts per account, recently received stats |
| Sync Status | Check if Mail.app is actively syncing |