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 [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.

Using the Codex Marketplace

Install the same public marketplace in Codex:

codex plugin marketplace add sweetrb/apple-mail-mcp
codex plugin add apple-mail@apple-mail-mcp

The Codex package registers the same apple-mail MCP server through npx -y apple-mail-mcp and includes the Apple Mail skill guidance.

Other Hosts (Hermes, Antigravity)

Configuration for two more hosts is included — each registers the same apple-mail MCP server (npx -y apple-mail-mcp):

• Hermes Agent (NousResearch) — Hermes has no plugin/marketplace drop-in. Add the server with hermes mcp add apple-mail --command npx --args -y apple-mail-mcp, or merge .hermes-plugin/config.yaml into ~/.hermes/config.yaml. Details: .hermes-plugin/README.md.
• Antigravity (Google) — add the server entry from .antigravity-plugin/mcp_config.json to ~/.gemini/config/mcp_config.json (or via Antigravity's MCP settings).

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