apple-mail-mcp
This MCP server provides programmatic access to Apple Mail on macOS, enabling AI assistants to read, send, search, and manage emails.
Account & Mailbox Management
List all configured email accounts
List, create, rename/move, and delete mailboxes (with optional cascade delete)
Reading & Searching Messages
Search messages by sender, subject, body, date range, read/flagged/attachment status; supports IMAP fast path or AppleScript fallback
Get full message details (body, headers, attachments) for one or more message IDs
Get all messages in a conversation thread
Aggregate inbox statistics (volume, read/unread/flagged counts, top senders) over a time window
Attachment Handling
Save attachments to a local directory
Read attachment content inline without saving to disk
Message Actions
Update messages: mark read/unread, flag/unflag, move to another mailbox
Delete messages (moves to Trash)
Drafts & Sending
Create drafts (new, reply, or forward) with HTML body, attachments, CC/BCC, and optional immediate send
Update existing drafts (delete-and-recreate with merged fields)
Delete drafts
Rules Management
List, create, update, and delete Mail.app rules with conditions and actions (move, copy, mark read/flagged, delete, forward)
Templates
List, get, save, and delete email templates with placeholder variables
Render a template with variable substitution (and optional reply context) to produce ready-to-send subject and body
Supports configuring IMAP access to AOL email for faster search and retrieval within Apple Mail.
Provides programmatic access to Apple Mail on macOS, enabling an AI to read, send, search, and manage emails, drafts, mailboxes, rules, and templates.
Supports configuring IMAP access to Gmail for faster search and retrieval within Apple Mail.
Supports configuring IMAP access to iCloud email for faster search and retrieval within Apple Mail.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apple-mail-mcp show me my latest emails from John"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.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, optionallysend_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-mcpClaude 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 scriptThen 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 --devConfiguration
Skip this section if you installed the
.mcpbbundle — 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 iCloudSubstitute 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
143for a server actually on993, so the implicit-TLS handshake fails withWRONG_VERSION_NUMBER— override with--host/--port <993>, which are persisted so runtime connects to the same coordinates (#405);prompts via
getpassso 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-renameapple-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 |
|
|
|
|
|
|
|
|
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 withsetup-imap+ Keychain.Caveat: the name→suffix mapping isn't reversible —
Yahoo!andYahooboth map toYAHOO, 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.comaliases as LOGIN username, not the Apple ID email. The server (andsetup-imap) readsemail addresses of accountfrom Mail.app for that reason. If your iCloud Apple ID is a third-party address (e.g. a@gmail.comApple ID) and Mail.app reports no@icloud.comaddress for the account, auto-detection can't find the right login —setup-imapwill fail with a hint to re-run with--email <your @icloud.com/@me.com address>. That--emailvalue 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 Mailis 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 auditBranch 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_attachmentsis byte-capped (per-attachment + aggregate) against disk-fill DoS
Docs:
SECURITY.md — vulnerability-reporting policy
docs/SECURITY.md — user-facing security posture & privacy
docs/guides/THREAT_MODEL.md — STRIDE trust-boundary analysis
docs/guides/SECURITY_CHECKLIST.md — per-feature contributor checklist
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
Available Tools
25 toolscreate_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_mailboxAIdempotent
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_draftADestructiveIdempotent
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_mailboxADestructiveIdempotent
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_messagesADestructiveIdempotent
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_ruleADestructiveIdempotent
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_templateADestructiveIdempotent
Delete a template by name.
Destructive — requires user confirmation via MCP elicitation before running.
Inputs: name (required). Returns: object
get_attachment_contentARead-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_messagesARead-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_statisticsARead-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_templateARead-onlyIdempotent
Read a single template by name.
Inputs: name (required). Returns: object
get_threadARead-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_accountsARead-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_mailboxesARead-onlyIdempotent
List all mailboxes for an account.
Inputs: account (required). Returns: object
list_rulesARead-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_templatesARead-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_templateARead-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_attachmentsBIdempotent
Save attachments from a message to a directory.
Inputs: message_id (required), save_directory (required), account, mailbox, +1 more. Returns: object
save_templateAIdempotent
Create or overwrite a template.
Inputs: body (required), name (required), subject. Returns: object
search_messagesARead-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.accountis required.source=[id1, id2, ...]: scope the search to the specific messages identified by the given ids.account/mailboxare 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_draftADestructiveIdempotent
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_mailboxADestructiveIdempotent
Rename and/or re-parent (move) an existing mailbox.
Two delivery paths:
Rename only (
new_nameset,new_parentisNone): AppleScript. Fast, no IMAP credentials needed.Move (
new_parentset; optionally combined with rename): IMAP RENAME. Requires IMAP credentials in Keychain (#73 opt-in flow) — returnserror_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_messageADestructiveIdempotent
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_ruleADestructiveIdempotent
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
Scored across 25 tools
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.
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.
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.
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
Related MCP Connectors
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Connect any mailbox to Claude, ChatGPT & AI: read, send, reply, schedule & search emails.
Connect Gmail, iCloud Mail, Outlook, Yahoo Mail, Fastmail and other IMAP inboxes to ChatGPT, Claude and compatible AI assistants. Find emails by meaning across languages with semantic search. Ask AI to find customer conversations, summarize deadlines and draft follow-ups. Give a sales rep access to a shared outreach inbox or bring email into a compatible CRM. Share an iCloud custom-domain inbox with teammates without their own Apple ID or iCloud+ plan. Search results may be incomplete or stale; separate permissions control mail actions.
Email for AI agents: read, search and send from your Gmail, Outlook, Yahoo, iCloud or IMAP inbox.
Related MCP Servers
- AlicenseBqualityAmaintenanceEnables 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.28213 PyPI257MIT
- AlicenseNot gradedqualityBmaintenanceEnables using Apple Mail accounts to search, read, manage, draft, and send messages from Codex or Claude Code locally.MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to read, search, send, and manage email on macOS through programmatic access to Apple Mail.29MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read, search, and manage email via IMAP, and send emails with attachments via SMTP, using natural language commands.546 npmMIT