apple-mail-fast-mcp: Skill for Claude Code

Apple Mail MCP Performance Patterns

The Core Insight

The bottleneck is per-subprocess overhead. Each osascript call costs 100-300ms regardless of what it does. All performance work reduces the number of subprocess calls.

Known Operation Timings

Operation	Time	Notes
Single osascript call overhead	100-300ms	Minimum cost per subprocess
search_messages (typical INBOX)	~1-5s	Depends on mailbox size and filter count
get_message (single)	<1s	Direct ID lookup
create_draft (with send_now=True)	~1-2s	Includes Mail.app compose + send
update_message (bulk read/flag)	~1-2s	Single script for N messages via _bulk_repeat_block
update_message (move)	~1-3s	Varies by account type (Gmail slower)
save_attachments	~2-5s	Depends on attachment count/size

Pattern 1: Use whose Clauses for Server-Side Filtering

-- GOOD: Server-side filter (fast, Mail.app evaluates internally)
set msgs to (messages of mbox whose sender contains "[email protected]")

-- BAD: Fetch all then filter in Python (slow, transfers all data)
set msgs to every message of mbox
-- then filter in Python loop

whose clauses let Mail.app filter internally without transferring unmatched messages over IPC. This is 10-50x faster for large mailboxes.

Pattern 2: Single Script Per Batch Operation

# GOOD: One osascript call for N messages (near-constant time)
script = """
tell application "Mail"
    repeat with msgId in {id1, id2, id3}
        set read status of (first message whose id is msgId) to true
    end repeat
end tell
"""
self._run_applescript(script)

# BAD: N osascript calls for N messages (linear time)
for msg_id in message_ids:
    self._run_applescript(f'tell application "Mail" ...')

Batch operations should always build a single AppleScript that handles all items.

Pattern 3: Use limit for Pagination

The search_messages tool accepts a limit parameter (default: 50). AppleScript uses items 1 thru N of for server-side limiting. Always pass a reasonable limit — fetching 10,000 messages when the user wants the latest 10 wastes time.