apple-mail-fast

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

Claude Desktop — install from file (.mcpb)

The lowest-friction path for Claude Desktop: grab the apple-mail-fast-mcp-<version>.mcpb bundle from the Releases page and open it (or drag it into Settings → Extensions). Claude Desktop manages Python and dependencies for you via uv — no manual venv, no config JSON to hand-edit. macOS only.

To build the bundle yourself: ./scripts/build-mcpb.sh → dist/apple-mail-fast-mcp-<version>.mcpb (requires Node for the mcpb packer).

Claude Code — install as a plugin

One command in Claude Code, no config JSON:

/plugin marketplace add s-morgan-jeffries/apple-mail-fast-mcp
/plugin install apple-mail-fast@apple-mail-fast-mcp

Claude Code launches the server via uv run from the plugin directory (resolves dependencies from the bundled pyproject.toml/uv.lock — no PyPI needed), so you only need uv installed. macOS only. See docs/reference/TOOLS.md for IMAP setup and the read/write split.

pip / uvx (any MCP client)

Published on PyPI:

uvx apple-mail-fast-mcp          # zero-install, run on demand
pip install apple-mail-fast-mcp  # or install the console script

Then point your MCP client at it — the config is a one-liner (no absolute paths):

{
  "mcpServers": {
    "apple-mail": { "command": "uvx", "args": ["apple-mail-fast-mcp"] }
  }
}

From source (development)

git clone https://github.com/s-morgan-jeffries/apple-mail-fast-mcp.git
cd apple-mail-fast-mcp
uv sync --dev

Configuration

Skip this section if you installed the .mcpb bundle — it wires up Claude Desktop for you. The manual config below is for source installs.

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