apple-mail

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 (attach by file path or inline base64 content)
Send Serial Email	Mail merge — send personalized emails to a list of recipients with {{placeholder}} support
Create Draft	Save emails to Drafts folder (attach by file path or inline base64 content)
Reply	Reply to messages (with reply-all support)
Forward	Forward messages to new recipients
Get Thread	Group a conversation by normalized subject (across AppleScript or IMAP)
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
Fetch Attachment	Get an attachment's bytes as base64 (no disk write)

Read/list/get tools also return structured JSON (structuredContent) alongside the text, so agents can consume results without parsing prose.

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