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 [email protected]"
• "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 |

Tool Reference

This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.

Message Operations

search-messages

Search for messages matching criteria. Searches all accounts by default.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | No | Text to search in subject/sender | | from | string | No | Filter by sender email address | | subject | string | No | Filter by subject line | | mailbox | string | No | Mailbox to search in (omit to search all mailboxes) | | account | string | No | Account to search in (omit to search all accounts) | | isRead | boolean | No | Filter by read status | | isFlagged | boolean | No | Filter by flagged status | | dateFrom | string | No | Start date filter (e.g., "January 1, 2026") | | dateTo | string | No | End date filter (e.g., "March 1, 2026") | | limit | number | No | Max results (default: 50) |

get-message

Get the full content of a message.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID | | preferHtml | boolean | No | Return HTML source instead of plain text |

Returns: Subject line and message body (plain text by default, HTML if preferHtml is true and HTML content is available).

list-messages

List messages in a mailbox.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mailbox | string | No | Mailbox name (omit to list from all mailboxes) | | account | string | No | Account name | | limit | number | No | Max messages (default: 50) | | offset | number | No | Number of messages to skip (for pagination) | | from | string | No | Filter by sender email address or name | | unreadOnly | boolean | No | Only show unread messages |

Returns: List of messages with ID, date, subject, and sender.

send-email

Send a new email immediately.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | to | string[] | Yes | Recipient addresses | | subject | string | Yes | Email subject | | body | string | Yes | Email body (plain text) | | cc | string[] | No | CC recipients | | bcc | string[] | No | BCC recipients | | account | string | No | Send from specific account | | attachments | string[] | No | Absolute file paths to attach, max 20 files (e.g., ["/Users/me/report.pdf"]) |

Example:

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "body": "Hi, just confirming our meeting at 2pm tomorrow.",
  "account": "Work",
  "attachments": ["/Users/me/Documents/agenda.pdf"]
}

send-serial-email

Send individual personalized emails to a list of recipients (mail merge). Each recipient receives their own email — recipients don't see each other. Supports {{placeholder}} tokens in both subject and body.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | recipients | object[] | Yes | List of recipients, max 100 (see below) | | subject | string | Yes | Email subject — use {{Key}} for placeholders | | body | string | Yes | Email body — use {{Key}} for placeholders | | account | string | No | Send from specific account | | delayMs | number | No | Delay between sends in ms (default: 500, max 10000) |

Each recipient object:

| Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Recipient email address | | variables | object | Yes | Key-value pairs for placeholder replacement |

Example:

{
  "recipients": [
    { "email": "[email protected]", "variables": { "Name": "Alice", "Company": "Acme" } },
    { "email": "[email protected]", "variables": { "Name": "Bob", "Company": "Globex" } }
  ],
  "subject": "Hello {{Name}}!",
  "body": "Dear {{Name}},\n\nGreat to connect about {{Company}}.\n\nBest regards"
}

Returns: Per-recipient success/failure results with a summary count.

create-draft

Save an email to Drafts without sending.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | to | string[] | Yes | Recipient addresses | | subject | string | Yes | Email subject | | body | string | Yes | Email body (plain text) | | cc | string[] | No | CC recipients | | bcc | string[] | No | BCC recipients | | account | string | No | Account for draft | | attachments | string[] | No | Absolute file paths to attach, max 20 files |

Returns: Confirmation that draft was created.

reply-to-message

Reply to an existing message.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID to reply to | | body | string | Yes | Reply body | | replyAll | boolean | No | Reply to all recipients (default: false) | | send | boolean | No | Send immediately (default: true, false = save as draft) |

Example - Reply to sender only:

{
  "id": "12345",
  "body": "Thanks for the update!"
}

Example - Reply all, save as draft:

{
  "id": "12345",
  "body": "I'll review this and get back to everyone.",
  "replyAll": true,
  "send": false
}

forward-message

Forward a message to new recipients.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID to forward | | to | string[] | Yes | Recipients to forward to | | body | string | No | Message to prepend | | send | boolean | No | Send immediately (default: true, false = save as draft) |

mark-as-read / mark-as-unread

Change read status of a message.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID |

flag-message / unflag-message

Flag or unflag a message.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID |

delete-message

Delete a message (move to trash).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID |

move-message

Move a message to a different mailbox.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID | | mailbox | string | Yes | Destination mailbox | | account | string | No | Account containing mailbox |

list-attachments

List attachments on a message.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID |

Returns: List of attachments with name, MIME type, and size.

save-attachment

Save a message attachment to disk.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Message ID | | attachmentName | string | Yes | Filename of the attachment | | savePath | string | Yes | Directory to save to |

Batch Operations

All batch operations accept an array of message IDs (max 100 per batch) and return per-item success/failure results.

batch-delete-messages

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ids | string[] | Yes | Message IDs to delete (max 100) |

batch-move-messages

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ids | string[] | Yes | Message IDs to move (max 100) | | mailbox | string | Yes | Destination mailbox | | account | string | No | Account containing mailbox |

batch-mark-as-read / batch-mark-as-unread

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ids | string[] | Yes | Message IDs (max 100) |

batch-flag-messages / batch-unflag-messages

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ids | string[] | Yes | Message IDs (max 100) |

Mailbox Operations

list-mailboxes

List all mailboxes for an account.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | account | string | No | Account to list from |

Returns: List of mailbox names with message and unread counts.

get-unread-count

Get unread message count.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | mailbox | string | No | Mailbox to check (omit for total) | | account | string | No | Account to check |

create-mailbox

Create a new mailbox.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Mailbox name | | account | string | No | Account to create in |

delete-mailbox

Delete a mailbox.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Mailbox name | | account | string | No | Account containing mailbox |

rename-mailbox

Rename a mailbox (creates new, moves messages, deletes old).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | oldName | string | Yes | Current mailbox name | | newName | string | Yes | New mailbox name | | account | string | No | Account containing mailbox |

Account Operations

list-accounts

List all configured Mail accounts.

Parameters: None

Returns: List of account names and email addresses.

Rules

list-rules

List all mail rules.

Parameters: None

Returns: List of rule names and enabled status.

enable-rule / disable-rule

Enable or disable a mail rule.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Rule name |

Contacts

search-contacts

Search contacts in Contacts.app.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Name to search for | | limit | number | No | Max results (default: 10) |

Returns: List of contacts with name, email addresses, and phone numbers.

Templates

Email templates are stored in memory for the duration of the server session.

save-template

Save or update an email template.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | name | string | Yes | Template name | | subject | string | Yes | Default subject line | | body | string | Yes | Template body | | to | string[] | No | Default recipients | | cc | string[] | No | Default CC recipients | | id | string | No | Template ID (for updating) |

list-templates

List all saved templates.

Parameters: None

get-template

Get a template by ID.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Template ID |

delete-template

Delete a template.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Template ID |

use-template

Create a draft from a template, with optional overrides.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | id | string | Yes | Template ID | | to | string[] | No | Override recipients | | cc | string[] | No | Override CC | | subject | string | No | Override subject | | body | string | No | Override body |

Diagnostics

health-check

Verify Mail.app connectivity and permissions.

Parameters: None

Returns: Status of all health checks (app running, permissions, account access).

get-mail-stats

Get mail statistics.

Parameters: None

Returns: Total and per-account message/unread counts, plus recently received stats (24h, 7d, 30d).

get-sync-status

Check Mail.app sync activity.

Parameters: None

Returns: Whether sync is detected, pending uploads, recent activity, and seconds since last change.

Usage Patterns

Basic Workflow

User: "Check my inbox for new emails"
AI: [calls list-messages]
    "You have 12 messages. Here are the most recent..."

User: "Show me emails from Sarah"
AI: [calls search-messages with query="Sarah"]
    "Found 3 emails from Sarah across all mailboxes..."

User: "Read the first one"
AI: [calls get-message with id="..."]
    "Subject: Project Update..."

Working with Accounts

By default, operations use Mail.app's configured default send account. Search operations check all accounts when no account is specified. To work with specific accounts:

User: "What email accounts do I have?"
AI: [calls list-accounts]
    "You have 3 accounts: iCloud, Gmail, Work Exchange"

User: "Show unread emails in my Work account"
AI: [calls list-messages with account="Work Exchange", mailbox="INBOX"]
    "Your Work account has 5 unread messages..."

Sending Emails Safely

User: "Draft an email to the team about the deadline"
AI: [calls create-draft with to=["team@..."], subject="...", body="..."]
    "I've created a draft. Please review it in Mail.app before sending."

User: "Send it"
AI: [User opens Mail.app and sends manually, or AI calls send-email]

Sending Personalized Emails (Mail Merge)

User: "Send a personalized email to Alice ([email protected]), Bob ([email protected]),
       and Carol ([email protected]). Subject: 'Project Update for {{Company}}',
       Body: 'Hi {{Name}}, here is the latest update for {{Company}}.'"
AI: [calls send-serial-email with recipients, subject template, and body template]
    "Successfully sent 3 email(s):
      - [email protected]: sent
      - [email protected]: sent
      - [email protected]: sent"

Organizing Messages

User: "Move all newsletters to Archive"
AI: [calls search-messages to find newsletters]
AI: [calls move-message for each, with mailbox="Archive"]
    "Moved 8 newsletters to Archive"

Installation Options

npm (Recommended)

npm install -g github:sweetrb/apple-mail-mcp

From Source

git clone https://github.com/sweetrb/apple-mail-mcp.git
cd apple-mail-mcp
npm install
npm run build

If installed from source, use this configuration:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/apple-mail-mcp/build/index.js"]
    }
  }
}

Security and Privacy

• Local only - All operations happen locally via AppleScript. No data is sent to external servers.
• Permission required - macOS will prompt for automation permission on first use.
• No credential storage - The server doesn't store any passwords or authentication tokens.
• Email safety - Use create-draft to review emails before sending.

Known Limitations

| Limitation | Reason | |------------|--------| | macOS only | Apple Mail and AppleScript are macOS-specific | | No sending HTML email | Emails are sent as plain text; reading HTML content is supported | | Attachments require absolute paths | File attachments must use full absolute paths (e.g., /Users/me/file.pdf) | | No smart mailboxes | Cannot access Smart Mailboxes via AppleScript | | In-memory templates | Email templates are not persisted across server restarts | | Numeric-only message IDs | Message IDs must contain only digits (validated by schema) | | Batch size cap | Batch operations are limited to 100 messages per request | | Date filter format | Date filters must be valid parseable dates (e.g., "January 1, 2026" or "2026-03-15"); bare numbers or non-date strings are rejected | | Attachment save path restrictions | save-attachment only allows saving to home directory, /tmp, /private/tmp, and /Volumes; path traversal is blocked | | Attachment count limit | send-email and create-draft accept a maximum of 20 file attachments |

Reply / Forward from Background Processes (Fixed in v1.4.0)

Prior to v1.4.0, reply-to-message and forward-message would send messages with empty body text when the MCP server ran as a background process (e.g., spawned via execSync from Node.js, which is how Claude Code invokes it).

Root cause: The AppleScript reply msg with opening window command creates a GUI compose window asynchronously. When set content runs immediately after, the window may not be ready, and the content assignment is silently ignored. Delays (delay 1, delay 2) were unreliable — the compose window's readiness depends on system load, Mail.app state, and whether the process has GUI access.

Fix: Replaced with opening window with without opening window for both reply and forward commands. With this approach, set content works immediately and reliably from background processes. In-Reply-To and References headers are still set correctly by Mail.app, and no GUI compose window is opened.

See #7 for full details and the list of approaches that were tested.

Backslash Escaping (Important for AI Agents)

When sending content containing backslashes (\) to this MCP server, you must escape them as \\ in the JSON parameters.

Why: The MCP protocol uses JSON for parameter passing. In JSON, a single backslash is an escape character. To include a literal backslash in content, it must be escaped as \\.

Example - Email with file path:

{
  "to": ["[email protected]"],
  "subject": "File Location",
  "body": "The file is at C:\\\\Users\\\\Documents\\\\report.pdf"
}

The \\\\ in JSON becomes \\ in the actual string, which represents a single \ in the email.

Common patterns requiring escaping:

• Windows paths: C:\Users\ → C:\\\\Users\\\\ in JSON
• Shell escaped spaces: Mobile\ Documents → Mobile\\\\ Documents in JSON
• Regex patterns: \d+ → \\\\d+ in JSON

If you see errors when sending emails with backslashes, double-check that backslashes are properly escaped in the JSON payload.

Troubleshooting

"Mail.app not responding"

• Ensure Mail.app is not frozen
• Try opening Mail.app manually
• Restart the MCP server

"Permission denied"

• macOS needs automation permission
• Go to System Preferences > Privacy & Security > Automation
• Ensure your terminal/Claude has permission to control Mail

"Message not found"

• Message may have been deleted or moved
• Message IDs change if the message is moved between mailboxes
• Use search-messages to find the current message ID

"Account not found"

• Account names must match exactly (case-sensitive)
• Use list-accounts to see exact account names

"Failed to send email"

• Check your network connection
• Verify Mail.app can send emails manually
• Check if the account is configured correctly in Mail.app

Development

npm install            # Install dependencies
npm run build          # Compile TypeScript
npm test               # Run unit tests
npm run test:integration  # Run integration tests (requires Mail.app)
npm run test:all       # Run all tests (unit + integration)
npm run lint           # Check code style
npm run format         # Format code

Author

Rob Sweet - President, Superior Technologies Research

A software consulting, contracting, and development company.

• Email: [email protected]
• GitHub: @sweetrb

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Related Projects

• apple-notes-mcp - MCP server for Apple Notes