apple-mail-mcp CLAUDE.md

CLAUDE.md — Apple Mail MCP Server

Project overview

Read-only Apple Mail MCP server. Exposes three tools to Claude Desktop via stdio transport. Uses AppleScript via subprocess — no third-party email libraries, no network calls.

Commands

# Start the server manually (for testing)
venv/bin/python apple_mail_mcp.py

# Syntax check
venv/bin/python -m py_compile apple_mail_mcp.py && echo "OK"

# Run the unit test suite (pure functions — no live Mail needed)
venv/bin/python -m pytest -q

# Reinstall dependencies into a fresh venv (runtime + dev)
python3 -m venv venv
venv/bin/pip install -r requirements.txt -r requirements-dev.txt

# Freeze current deps (after adding a new package)
venv/bin/pip freeze > requirements.txt

Architecture

Single file: all server logic lives in apple_mail_mcp.py. Do not split into multiple files.

Transport: stdio only. The server never opens a network socket.

AppleScript execution:

• Run via asyncio.create_subprocess_exec("osascript", "-e", script)
• 60-second async timeout with proc.kill() on expiry
• All user strings pass through _sanitize_for_applescript() before embedding
• Line continuation: AppleScript uses ¬ (U+00AC), NOT \. When scripts are passed via osascript -e, the parser is strict — a \ at end of line produces error -2741 ("Expected expression but found unknown token"). Always use sequential assignment statements instead of multi-line expressions.

Search strategy (mail_search_emails):

• Pipeline (v1.3.0): each mailbox emits up to limit newest matches (per-mailbox cap, NOT per-account) → Python _parse_search_rows() parses the delimited rows → _merge_results() dedups by (account, message_id), sorts newest-first, truncates to limit. This replaced the old "concatenate per-account outputs, truncate at limit in account order" loop, which let the first responding account fill the whole result list and silently drop other accounts (bug B1). Any message in the true global top-limit is within the newest limit of its own mailbox, so per-mailbox collection + global sort is exact.
• Sortable timestamp: each row carries a relative-seconds field (date received) - refDate, where refDate = (current date) is captured once at script start. It is always a small negative integer. Never emit absolute epochs — AppleScript mangles large integers (32-bit/scientific-notation hazard); relative seconds avoid that and need no GMT correction. _parse_search_rows reads it via int(float(...)).
• Skip list (default): Trash, Deleted Messages, Deleted Items, Junk, Junk Email, Junk E-mail, Spam, Bulk Mail, Bulk, All Mail, [Gmail]All Mail, Important, Starred, Outbox. Covers real-world junk/trash names across iCloud/Yahoo/Gmail/Hotmail plus Gmail duplicate-view mailboxes (fixes B2/B3). include_all_mailboxes=true opts back in; an explicit mailbox_name bypasses the skip list.
• whose clause builds its predicate dynamically from active filters (keyword, since_days, before_days). Why whose instead of search: Mail 16 (macOS 26) removed the search <mailbox> for <keyword> command.
• whose is O(n) per mailbox at the Objective-C layer (~0.5–1.5k msgs/sec) — it fully materialises the match list before the per-mailbox cap applies. Low limit reduces output size, not scan cost. Because there is no global early-exit anymore, all non-skipped mailboxes are scanned; date-only wide-window searches are the slow case.
• before_days bounds the near edge of the window (date received <= (current date) - (N * days)); requires since_days and must be < since_days (enforced by the validator). Use it to page older mail without re-fetching.
• Multi-account parallel execution: when no account filter is set, the tool first calls _SCRIPT_LIST_ACCOUNTS to enumerate accounts, then runs one search script per account via asyncio.gather(return_exceptions=True) with a 45 s per-account timeout. A slow/offline IMAP account cannot block or crash results from other accounts. Timed-out accounts are listed as a warning in the response.
• When account is specified, a single script runs with a 60 s timeout (no gather overhead).
• Do NOT call proc.stdout.close() or proc.stderr.close() on timeout — asyncio.StreamReader has no .close() method. Use only proc.kill() + await proc.wait().