Skip to main content
Glama
apple-mail-mcp

apple-mail-mcp

Apple Mail MCP Server

Tests Python 3.10+ License: MIT

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.11.0) 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.

Related MCP server: Mailbridge for Apple Mail

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

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.

Permissions

On first run, macOS will prompt for Automation access. Grant permission in: System Settings > Privacy & Security > Automation > Terminal (or your IDE)

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 — the setup-imap subcommand walks you through it:

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

Substitute the Mail.app account name exactly — whatever it's labeled in Mail.app (e.g. iCloud, Gmail, "Yahoo!"). The guided flow (#384):

  • detects your provider from the account's IMAP host and points you at the right app-password page — iCloud (account.apple.com → App-Specific Passwords), Gmail (myaccount.google.com/apppasswords), Yahoo, Outlook, Fastmail (generic guidance for anything else) — with the provider's 2FA steps, and offers to open the page in your browser;

  • explains that this is a scoped, revocable app-specific password — limited to that one account — unlike granting full disk access;

  • looks up the account's primary email from Mail.app (override with --email, which is persisted so runtime uses the same login — see the iCloud quirk below);

  • reads the IMAP host and port from Mail.app; if either is wrong — some institutional servers (e.g. Zimbra) scriptably misreport the port as 143 for a server actually on 993, so the implicit-TLS handshake fails with WRONG_VERSION_NUMBER — override with --host / --port <993>, which are persisted so runtime connects to the same coordinates (#405);

  • prompts via getpass so the password never lands in shell history;

  • writes to Keychain at apple-mail-fast-mcp.imap.<account> (idempotent — re-running with a new password updates the entry; pre-rename apple-mail-mcp.imap. entries still resolve via a read-through fallback removed at 1.0.0);

  • opens an IMAP connection and runs a real LOGIN to confirm the password works. On rejection it rolls back the Keychain entry and lets you paste again (up to 3 tries) so a bad password never leaves a broken item behind.

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:

Account name

Environment variable

iCloud

APPLE_MAIL_MCP_IMAP_PASSWORD_ICLOUD

Gmail

APPLE_MAIL_MCP_IMAP_PASSWORD_GMAIL

Yahoo!

APPLE_MAIL_MCP_IMAP_PASSWORD_YAHOO

My Gmail

APPLE_MAIL_MCP_IMAP_PASSWORD_MY_GMAIL

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))"

If IMAP is working, the call returns in ~1 second. If it logs a WARNING about falling back (visible with --log-level=DEBUG), check that the account name matches Mail.app's account name exactly and that the email in your Keychain entry matches what email addresses of account returns.

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.

Compose operations can use IMAP APPEND for drafts and SMTP for send_now=true when the required credentials and account/seed information are available. Eligible calls fall back to AppleScript when those paths cannot engage. See the architecture reference for dispatch details.

Development

# Setup
uv sync --dev

# Common commands
make test              # Run unit tests
make lint              # Lint with ruff
make typecheck         # Type check with mypy
make check-all         # All checks (lint, typecheck, test, complexity, version-sync, parity)
make coverage          # Coverage report
make test-integration  # Integration tests (requires Mail.app)

# Validation scripts
./scripts/check_version_sync.sh          # Version consistency
./scripts/check_client_server_parity.sh  # Connector-server alignment
./scripts/check_complexity.sh            # Cyclomatic complexity
./scripts/check_applescript_safety.sh    # AppleScript safety audit

Branch Convention

{type}/issue-{num}-{description} — e.g., feature/issue-42-thread-support

Architecture

server.py (FastMCP tools — thin orchestration, validation, elicitation gates)
  -> mail_connector.py (dispatch + domain logic)
     -> AppleScript path:  subprocess.run(["osascript", ...]) -> Apple Mail.app   (universal baseline)
     -> IMAP fast path:    imap_connector.py -> the account's IMAP server          (when hinted + Keychain creds)

Dispatch model. AppleScript is the baseline for many operations. When a read/mutation call supplies an account (and, where relevant, mailbox) hint and the account has IMAP credentials, the connector can take a server-side IMAP fast path. Eligible failures use AppleScript fallback where available; some operations require IMAP, and fallback can be slower or less complete. See docs/reference/ARCHITECTURE.md for the full dispatch model, the dual-emit message-ID scheme, the drafts lifecycle, and the IMAP thread tiers.

  • server.py — MCP tool registration, input validation, confirmation (elicitation) gates, response formatting

  • mail_connector.py — AppleScript generation/execution + IMAP-fast-path dispatch

  • imap_connector.py — IMAP client + connection pool (search, fetch, bulk-mutation fast paths)

  • security.py — Input sanitization, audit logging, confirmation flows

  • utils.py — Pure functions: escaping, parsing, validation

  • exceptions.py — Typed exception hierarchy

Security

  • Local execution only (no cloud processing)

  • Uses existing Mail.app authentication; IMAP app-passwords (opt-in) live in the macOS Keychain, never in the repo or config

  • All inputs sanitized and AppleScript-escaped (defense against AppleScript injection)

  • Destructive operations require user confirmation via MCP elicitation; rate limits + audit logging on top

  • save_attachments is byte-capped (per-attachment + aggregate) against disk-fill DoS

Docs:

Contributing

See CONTRIBUTING.md for development workflow, coding standards, and PR process. For agent-assisted development, start with AGENTS.md and the Codex setup guide.

License

MIT

Available Tools

25 tools
create_draftA

Create a draft (fresh, reply, or forward). Optionally send immediately.

Mail.app's actual primitive is the draft — every outgoing message is a draft until sent. This tool lets callers create one, optionally seeded from an existing message (reply or forward), and either save it for later or send it now.

Inputs: cc, to, bcc, body, +11 more. Returns: object

create_mailboxA
Idempotent

Create a new mailbox/folder.

Inputs: name (required), account (required), parent_mailbox. Returns: object

create_ruleA

Create a new Mail.app rule.

Rules with actions that can move, forward, or delete mail (delete / forward_to / move_to / copy_to) require user confirmation — a single create can install automation that auto-forwards or deletes all future mail (#222). Organizational-only rules (mark_read, mark_flagged, flag_color) are created without a prompt. Mail.app appends new rules to the end of the rule list, so the returned rule_index equals the new total rule count.

Inputs: name (required), actions (required), conditions (required), enabled, +1 more. Returns: object

delete_draftA
DestructiveIdempotent

Delete (move to Trash) an existing draft.

Lifecycle endpoint for cancellation. Mail.app moves the message to the Deleted Messages mailbox; recovery is technically possible but Mail.app no longer treats trashed drafts as editable, so this is effectively a one-way discard. No elicitation (recoverable from Trash) and no rate limit (local operation).

Inputs: draft_id (required). Returns: object

delete_mailboxA
DestructiveIdempotent

Delete a mailbox via IMAP.

Mail.app's AppleScript dictionary doesn't expose a working delete primitive for mailboxes, so this operation goes through IMAP. Requires IMAP credentials in Keychain (#73 opt-in flow) — returns error_type: "imap_required" when missing.

Always elicits user confirmation (destructive). By default refuses non-empty mailboxes to prevent accidental data loss; pass delete_messages=True to cascade.

Refused (#164): targeting the bare [Gmail] parent or any [Gmail]/... child path returns error_type: "unsupported_gmail_system_label". Gmail's IMAP server doesn't support DELETE for these paths.

Inputs: name (required), account (required), delete_messages. Returns: object

delete_messagesA
DestructiveIdempotent

Delete messages (always moves to the account's Trash mailbox).

Destructive: gated behind user confirmation via MCP elicitation (issue #239), matching delete_rule / delete_mailbox / delete_template.

Inputs: message_ids (required), account, permanent, source_mailbox. Returns: object

delete_ruleA
DestructiveIdempotent

Delete a Mail.app rule by 1-based positional index.

Destructive — requires user confirmation via MCP elicitation before running. Cannot be undone (Mail.app does not version rule history).

Inputs: rule_index (required). Returns: object

delete_templateA
DestructiveIdempotent

Delete a template by name.

Destructive — requires user confirmation via MCP elicitation before running.

Inputs: name (required). Returns: object

get_attachment_contentA
Read-onlyIdempotent

Read one attachment's content inline, without writing it to disk.

For "triage" workflows where you want to inspect an attachment (a text file, JSON, a small PDF) before deciding what to do with it — instead of save_attachments → read the file → clean up.

Inputs: message_id (required), attachment_index (required), account, mailbox. Returns: object

get_messagesA
Read-onlyIdempotent

Get full details of one or more messages, with bodies.

Returns a list of message dicts (possibly of length 0 or 1). Pair with search_messages (metadata-only) and get_thread (thread member ids) to fetch bodies for specific messages.

Inputs: message_ids (required), account, mailbox, body_format, +3 more. Returns: object

get_statisticsA
Read-onlyIdempotent

Aggregate inbox statistics over a mailbox and time window.

A read-only analytics roll-up computed from a single search_messages pass — message volume, read/unread/flagged counts, read ratio, and the top senders (by full address or domain). This is the consolidated inbox-stats tool; per-folder unread counts live on list_mailboxes and are not duplicated here.

The window defaults to the last ~30 days (received_within_hours=720); pass date_from/date_to for an explicit range. Stats are computed over at most scan_limit of the most recent messages in the window — window_fully_covered is False when the window held more than that, so the numbers are a recent-sample rather than a silent truncation.

Inputs: account (required), by, date_to, mailbox, +4 more. Returns: object

get_templateA
Read-onlyIdempotent

Read a single template by name.

Inputs: name (required). Returns: object

get_threadA
Read-onlyIdempotent

Return all messages in the thread containing the given message.

Looks up the anchor message by its id, then reconstructs the conversation via the connector's tiered IMAP threading dispatch (Tier 1 X-GM-THRID for Gmail, Tier 3 header-search BFS fallback) or the AppleScript path. Result rows are sorted by date_received ascending.

The returned ids can be piped into search_messages(source=[ids]) for filtered metadata or get_messages([ids]) for full bodies.

Known limitation: thread members whose subject was rewritten mid-conversation are missed on the AppleScript fallback path (subject prefilter tradeoff).

Inputs: message_id (required). Returns: object

list_accountsA
Read-onlyIdempotent

List all configured email accounts in Apple Mail.

Returns each account's id (UUID), display name, email addresses, account type, and enabled state. Account ids are stable across name changes; prefer them over names for identifying accounts.

Returns: Dictionary containing the accounts list.

Example: >>> list_accounts() {"success": True, "accounts": [ {"id": "B21B254B-...", "name": "Gmail", "email_addresses": ["me@gmail.com"], "account_type": "imap", "enabled": True}, ... ]}

Inputs: no named parameters. Returns: object

list_mailboxesA
Read-onlyIdempotent

List all mailboxes for an account.

Inputs: account (required). Returns: object

list_rulesA
Read-onlyIdempotent

List all Mail.app rules (read-only).

Returns each rule's display name and enabled state. Rule names are NOT guaranteed unique — Mail allows duplicates — and rules have no stable id via AppleScript. This tool is read-only; mutation (enable/disable, create, delete) is tracked as a separate enhancement.

Returns: Dictionary containing the rules list.

Example: >>> list_rules() {"success": True, "rules": [ {"name": "Junk filter", "enabled": True}, {"name": "News From Apple", "enabled": False}, ... ], "count": 2}

Inputs: no named parameters. Returns: object

list_templatesA
Read-onlyIdempotent

List all stored email templates.

Templates live as files at ~/.apple_mail_mcp/templates/.md. Override the location with the APPLE_MAIL_MCP_HOME environment variable.

Returns: Dictionary with each template's name and subject (or null if no subject header is set).

Inputs: no named parameters. Returns: object

render_templateA
Read-onlyIdempotent

Render a template into ready-to-send subject and body text.

No side effects — caller is responsible for passing the rendered text to create_draft or update_draft (with send_now=True when ready to send).

With message_id, the original sender's display name and email, the original subject, and today's date are auto-populated as recipient_name, recipient_email, original_subject, and today. Without message_id, only today is auto-filled. User-supplied vars always override auto-fills on conflict.

Inputs: name (required), vars, message_id. Returns: object

save_attachmentsB
Idempotent

Save attachments from a message to a directory.

Inputs: message_id (required), save_directory (required), account, mailbox, +1 more. Returns: object

save_templateA
Idempotent

Create or overwrite a template.

Inputs: body (required), name (required), subject. Returns: object

search_messagesA
Read-onlyIdempotent

Search for messages matching criteria. Returns metadata-only rows.

Two corpus modes:

  • source=None (default): search the given account/mailbox using the IMAP/AppleScript SEARCH path. account is required.

  • source=[id1, id2, ...]: scope the search to the specific messages identified by the given ids. account/mailbox are ignored; the connector resolves each id self-sufficiently. The resulting message dicts are post-filtered by the other criteria (sender_contains, read_status, etc.) — full filter composition. The literal token "SELECTED" may appear in the list and is server-resolved at call time to Mail.app's current UI selection (zero-or-more messages). Mixed lists like ["SELECTED", "12345"] are valid. Missing ids drop out silently (partial-results).

For thread retrieval, call get_thread(message_id) to expand an anchor into thread member ids, then optionally pipe those ids into source=[ids] for filtered metadata browsing or into get_messages([ids]) for full bodies.

Inputs: limit, source, account, date_to, +11 more. Returns: object

update_draftA
DestructiveIdempotent

Update an existing draft. Implemented as delete-and-recreate.

Returns a NEW draft_id — Mail.app forbids mutating saved drafts, so update is implemented by reading the draft's current state, deleting it, and creating a new draft with the merged fields. Threading headers (for reply seeds) and forward anchor are preserved via persisted seed metadata.

Field merge semantics: any non-None argument overrides the existing value. None keeps the existing value. attachment_paths=None PRESERVES existing attachments (extracted via Mail's save command); [] explicitly clears them; a list replaces.

For drafts created externally (not via create_draft), seed recovery falls back to scanning Mail.app for the In-Reply-To header — this can be slow on large mailboxes (~30s+ per call). Forward seeds without disk state are misclassified as fresh; pass an explicit body if so.

Inputs: draft_id (required), cc, to, bcc, +8 more. Returns: object

update_mailboxA
DestructiveIdempotent

Rename and/or re-parent (move) an existing mailbox.

Two delivery paths:

  • Rename only (new_name set, new_parent is None): AppleScript. Fast, no IMAP credentials needed.

  • Move (new_parent set; optionally combined with rename): IMAP RENAME. Requires IMAP credentials in Keychain (#73 opt-in flow) — returns error_type: "imap_required" when missing.

At least one of new_name / new_parent must be provided.

Refused (#164): operations targeting the bare [Gmail] parent or any [Gmail]/... child path return error_type: "unsupported_gmail_system_label". Applies to both the source name and the resulting destination (new_parent join). Gmail's IMAP server doesn't support normal RENAME semantics for these paths; user-created Gmail labels (Newsletters, etc.) behave normally.

Inputs: name (required), account (required), new_name, new_parent. Returns: object

update_messageA
DestructiveIdempotent

Update one or more messages: change read state, flag, and/or move, in one atomic call (#135).

Patch semantics — caller specifies only the fields to change. All specified mutations apply in a single AppleScript pass via the bulk-update helper. Replaces the previous mark_as_read, move_messages, and flag_message tools.

Order of operations (matters for IMAP): read-state and flag changes apply first (in source mailbox), then the move. IMAP requires the message to exist in the source folder for STORE before MOVE.

Inputs: message_ids (required), account, flagged, flag_color, +4 more. Returns: object

update_ruleA
DestructiveIdempotent

Update an existing Mail.app rule (patch semantics).

Patch semantics: only fields you provide are changed. conditions and actions, when provided, REPLACE their respective structures wholesale (not merged).

Conditional confirmation: prompts the user via MCP elicitation when the patch touches conditions or match_logic (which alter matching scope), or replaces actions with a set that includes a dangerous action (move / forward / delete / copy). An actions patch limited to organizational flags (mark_read / mark_flagged / flag_color) skips the prompt, as do patches limited to enabled and/or name (trivially reversible). The enable/disable path replaces the removed set_rule_enabled tool: call update_rule(rule_index, enabled=True|False).

Refuses to update any rule whose existing actions include something outside the supported schema (run-AppleScript, redirect, reply text, play sound, custom highlight color); raises MailUnsupportedRuleActionError. Edit such rules in Mail.app's UI.

Inputs: rule_index (required), name, actions, enabled, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 25 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action: mailboxes, messages, drafts, rules, templates, accounts, attachments, and statistics are well separated. Even similarly named tools like search_messages, get_messages, and get_thread are explicitly differentiated by metadata-only vs. full-body vs. thread-expansion behavior.

    Naming Consistency5/5

    The entire tool set follows a consistent verb_noun pattern: list_, get_, create_, update_, delete_, save_, render_, search_. There are no mixed casing styles or vague verbs, making the surface highly predictable.

    Tool Count3/5

    At 25 tools, the server is at the heavy end of the recommended range, though the breadth of the Apple Mail domain partially justifies it. A few convenience tools like get_statistics and get_attachment_content could potentially be consolidated without losing core capability.

    Completeness5/5

    The tool set provides full lifecycle coverage for mailboxes, drafts, templates, and rules, plus message search/retrieval/update/delete, threading, attachments, and statistics. Workflows like search → fetch bodies → act, or render template → create draft → send, have no dead ends.

    Maintenance

    ActivityStale
    ResponsivenessMostly unanswered

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Enables AI assistants to interact with Apple Mail through natural language, providing comprehensive email management including reading, searching, composing, organizing, and analyzing emails across all configured accounts. Includes an expert skill system that teaches intelligent email workflows and productivity strategies.
      28
      213 PyPI
      257
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read, search, send, and manage email on macOS through programmatic access to Apple Mail.
      29
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read, search, and manage email via IMAP, and send emails with attachments via SMTP, using natural language commands.
      546 npm
      MIT