Apple Mail MCP Server

An MCP server that provides programmatic access to Apple Mail, enabling AI assistants like Claude to read, send, search, and manage emails on macOS.

⚠️ Pre-1.0 — expect breaking changes. The MCP tool surface (tool names, parameters, return shapes) is still evolving as the project matures. Pin to a specific version (for example, apple-mail-fast-mcp==0.10.2) and review the CHANGELOG before upgrading.

Tools (25)

Grouped by lifecycle (11 read-only, 14 mutating):

• Discovery — list_accounts, list_mailboxes, list_rules, list_templates: enumerate what's configured (no external cache — call per account).
• Read — search_messages, get_messages, get_thread, get_statistics, get_attachment_content, get_template, render_template: read messages/threads, aggregate inbox stats, pull an attachment's content inline, and render templates.
• Message actions — update_message (read/flag/move in one pass), delete_messages (→ Trash), save_attachments (to disk, byte-capped).
• Drafts — create_draft (new / reply / forward, optionally send_now), update_draft, delete_draft.
• Mailbox CRUD — create_mailbox, update_mailbox (rename or move), delete_mailbox.
• Rules — create_rule, update_rule, delete_rule.
• Templates (write) — save_template, delete_template.

Destructive operations (delete_*, create_rule with move/forward/delete actions, create_draft with send_now=true) prompt for confirmation via MCP elicitation. See docs/reference/TOOLS.md for full parameters and return shapes.

Prerequisites

• macOS 10.15 (Catalina) or later
• Python 3.10 or later
• Apple Mail configured with at least one account
• uv (recommended) or pip

Installation

# From source (recommended for development)
git clone https://github.com/s-morgan-jeffries/apple-mail-fast-mcp.git
cd apple-mail-fast-mcp
uv sync --dev

Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json). uv sync installs a console script at .venv/bin/apple-mail-fast-mcp; point Claude Desktop at its absolute path — it's the most reliable form under Claude Desktop's restricted spawn environment (no reliance on uv being on PATH):

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp"
    }
  }
}

(Equivalent alternative if you prefer driving it through uv: "command": "uv", "args": ["--directory", "/path/to/apple-mail-fast-mcp", "run", "apple-mail-fast-mcp"].)

Optional: split read / write servers

Claude Desktop prompts per-tool for permission. If you want to batch-approve the 9 read tools (list / search / get) and still gate the 14 mutating tools per call, run the connector twice — once with --read-only, once without — under two separate mcpServers entries:

{
  "mcpServers": {
    "apple-mail-read": {
      "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp",
      "args": ["--read-only"]
    },
    "apple-mail-write": {
      "command": "/path/to/apple-mail-fast-mcp/.venv/bin/apple-mail-fast-mcp"
    }
  }
}

The --read-only server exposes only the 9 read tools, so Claude Desktop's per-server permission UI naturally groups them. The full server still gates writes individually. Trade-off: 2× connector processes. See docs/reference/TOOLS.md for the per-tool classification and a no

... View full README on GitHub