Apple Mail MCP 助手

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"] }
  }
}

Setup

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

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 note on MCP annotation hints (readOnlyHint / destructiveHint / idempotentHint) which forward-compatible hosts may use to provide the same UX without the split.

Optional: faster search via IMAP

search_messages works out of the box via AppleScript. For large mailboxes (thousands of messages), AppleScript's whose clause can take 1–5 seconds per query. If you want faster server-side search, you can enable IMAP delegation per account by adding a Keychain entry.

How it works. If credentials exist for an account, the server uses IMAP (fast, server-side SEARCH). Otherwise — or on any IMAP failure (offline, wrong password, timeout) — it silently falls back to AppleScript. You never lose functionality; you only gain speed when IMAP is configured and reachable. The normal opt-in is a Keychain entry (below); an environment-variable fallback (further down) covers contexts where the Keychain isn't usable.

One-time setup per account.

1. Generate an app-specific password at your provider. The procedure varies: - iCloud: appleid.apple.com/account/manage → App-Specific Passwords. Requires 2FA on your Apple ID (default). - Gmail: myaccount.google.com/apppasswords. Requires 2-Step Verification on your Google account. - Yahoo / Fastmail / AOL: generate an app password in the provider's account-security settings.

2. Run the setup-imap subcommand. It prompts for the password (no echo), writes the Keychain entry, and verifies by connecting:

   apple-mail-fast-mcp setup-imap --account iCloud
   

1. If you see a one-time "security wants to use the 'login' keychain" prompt on the next IMAP-backed call, click Always Allow.

To remove the entry later: apple-mail-fast-mcp setup-imap --account iCloud --uninstall.

Environment-variable fallback (uvx / headless / CI)

Some contexts have no usable Keychain: uvx runs (ephemeral binary paths break the Keychain ACL, causing re-prompts or failures), Docker / CI (no Keychain at all), and background services (the ACL prompt blocks forever with no UI attached). For those, you can supply the IMAP password via an environment variable instead:

APPLE_MAIL_MCP_IMAP_PASSWORD_<SUFFIX>

<SUFFIX> is the Mail.app account name uppercased, with each run of non-alphanumeric characters collapsed to a single underscore and leading/trailing underscores trimmed:

When set to a non-empty value, the env var is used in preference to any Keychain entry for that account (it's checked first, with no security shell-out). An empty or whitespace-only value is ignored and the Keychain path is used. The lookup composes with the name↔UUID fallback, so an env var keyed on the account name is still found when a caller passes the account's UUID.

⚠️ Security tradeoff. Environment variables are far less private than the Keychain — they're visible via ps -E, launchctl getenv, /proc-style introspection, and process crash dumps, and they're easy to leak into logs or shell history. Use this only when the Keychain genuinely isn't an option (uvx, Docker, CI, headless). For Claude Desktop and standard local installs, stick with setup-imap + Keychain. Caveat: the name→suffix mapping isn't reversible — Yahoo! and Yahoo both map to YAHOO, and an account name with no ASCII letters/digits has no env-var form (use the Keychain for those).

Verifying the setup. The setup-imap command does this for you. If you want to spot-check post-hoc:

uv run python -c "from apple_mail_fast_mcp.mail_connector import AppleMailConnector; \
    print(AppleMailConnector().search_messages(account='<ACCOUNT_NAME>', limit=1))"

Known provider quirks.

• iCloud: the IMAP server accepts @icloud.com / @me.com aliases as LOGIN username, not the Apple ID email. The server (and setup-imap) reads email addresses of account from Mail.app for that reason. If your iCloud Apple ID is a third-party address (e.g. a @gmail.com Apple ID) and Mail.app reports no @icloud.com address for the account, auto-detection can't find the right login — setup-imap will fail with a hint to re-run with --email <your @icloud.com/@me.com address>. That --email value is persisted (in ~/.apple_mail_mcp/imap_login_overrides.json) so runtime resolution uses the same login (#341). It's a general override — use it for any account whose auto-detected IMAP login is wrong.
• Yahoo: app passwords have been progressively deprecated; the option may not be available for all accounts. If Yahoo's account-security page doesn't show the option, IMAP setup isn't possible for that account and AppleScript is the only path.
• Gmail: requires 2-Step Verification enabled. If your Google Workspace admin has disabled app passwords at the tenant level, IMAP setup isn't possible for that account.
• Gmail thread retrieval — All Mail visibility tradeoff. find_thread_members (used internally by thread-aware queries) is fastest when [Gmail]/All Mail is exposed over IMAP — that path is ~5 round-trips, mailbox-count-independent. Many users hide All Mail (Gmail Settings → Forwarding and POP/IMAP → Folder size limits → "Do not show in IMAP") because it duplicates every message. When hidden, the connector falls back to a per-mailbox X-GM-THRID iteration (still ~6× faster than the universal BFS, but proportional to your label count — ~25s on a 92-label account). Expose All Mail if you want the headline speed; keep it hidden if you prefer the cleaner IMAP folder list.

Write operations (create_draft, update_draft, including the send_now=true send path) always use AppleScript regardless of IMAP configuration — these need Mail.app's compose UI.