v0.2.4

Fixes

• List parameters now tolerate client-side string serialization. Some MCP clients (observed live: Cowork) send array arguments as a JSON string ('["/path/a.pdf"]') or a bare string; strict list[str] validation rejected these with "Input should be a valid list" — e.g. manage_drafts/compose_email created the draft but silently without its attachments. All list-typed parameters (attachments, message_ids) now accept a real list, a JSON-stringified list, or a single bare string (treated as a one-item list). The advertised JSON schema is unchanged (plain array of strings). Verified end-to-end through FastMCP's real call pipeline.
• Carries v0.2.3's cross-account move_email (to_account) and v0.2.2's no-crash-without-Full-Disk-Access fixes.

Install from this release (no PyPI needed)

uv tool install --force ./cobos_apple_mail_mcp-0.2.4-py3-none-any.whl
# or single-file .pyz — run with Python 3.12 (the ABI it was built for):
python3.12 apple-mail-mcp.pyz serve   # -full.pyz adds [watch]+[semantic]+[attachments]

Verify with shasum -a 256 -c SHA256SUMS.txt.

v0.2.3

Fixes

• move_email can now move messages across accounts. Previously the destination mailbox was only ever resolved in the message's own account, so a cross-account move failed with target mailbox not found (-2700), and passing the destination as the source account hint triggered the resolver's broad scan (20s timeout). New to_account parameter (MCP tool + CLI --to-account) resolves the destination mailbox in the named account — nested/sub-mailboxes included — with a clear error that points at to_account; undo_last moves the message back to its source account. account/mailbox remain source hints (where the message currently is), not the destination.
• Also carries v0.2.2's fix: the server no longer crashes on missing Full Disk Access — it starts and logs a clear warning.

Install from this release (no PyPI needed)

uv tool install --force ./cobos_apple_mail_mcp-0.2.3-py3-none-any.whl
# or single-file .pyz — run with Python 3.12 (the ABI it was built for):
python3.12 apple-mail-mcp.pyz serve   # -full.pyz adds [watch]+[semantic]+[attachments]

Verify with shasum -a 256 -c SHA256SUMS.txt.

v0.2.2

Same fix as the (unpublished) v0.2.1 — re-tagged because GitHub's immutable
releases permanently bound the v0.2.1 tag to a release created without assets.

Fixes

• Don't crash the server when Full Disk Access is missing. When a GUI MCP client (e.g. Claude Desktop) launches the server as a subprocess without Full Disk Access, find_mail_directory() used to raise PermissionError out of startup and the whole server exited — the client showed "Server disconnected" with a bare traceback. The server now starts anyway and logs a clear, actionable Full-Disk-Access warning; read/search/index tools report full_disk_access_denied until the grant is in place, while write tools (Mail.app scripting, gated by Automation) keep working. New library_mail_permission_denied() helper distinguishes "denied" from "no mailbox"; regression test included.

Install from this release (no PyPI needed)

# wheel (persistent CLI):
uv tool install --force ./cobos_apple_mail_mcp-0.2.2-py3-none-any.whl
# or single-file .pyz — run with Python 3.12 (the ABI it was built for):
python3.12 apple-mail-mcp.pyz serve
# -full.pyz additionally bundles [watch]+[semantic]+[attachments].

Verify with shasum -a 256 -c SHA256SUMS.txt. Then grant the app running the server
Full Disk Access (System Settings → Privacy & Security) — see the wiki's
Permissions & troubleshooting for the "Server disconnected" symptom and fix.

v0.2.0

cobos-apple-mail-mcp v0.2.0

Adds five capabilities and fixes several real bugs found by verifying every write path against a live Mail.app (not just mocked tests). 31 MCP tools now (up from 25).

New features

• Mail rules — list_rules reads every rule (conditions + actions) live via JXA; enable_rule/disable_rule/delete_rule manage their lifecycle (delete_rule always needs confirm=true and isn't undoable). No create_rule: Apple Mail's scripting genuinely cannot create rule conditions — documented, not faked.
• Flag-color tags — update_email_status action=set_flag_color color=red|orange|yellow|green|blue|purple|gray, plus a flag_color filter on search and get_emails. Undoable.
• Attachment content search — optional [attachments] extra: extracts PDF (pypdf) / DOCX (stdlib zip+XML, no compiled deps) text so search scope=attachments matches content, not just filenames. Off by default; backfill via index extract-attachments.
• Unsubscribe — unsubscribe_from_sender: RFC-8058 one-click https POST (https-only, timeout, no downgrade redirect) with a mailto fallback; returns method=one-click-post|mailto|none-found.
• Browsable contacts — list_contacts (search/browse), bidirectional (counts both mail received from and sent to each address).

Bug fixes (found by real-Mac verification)

• Write-tool resolution timed out on any real mailbox: the resolver queried whose message id with angle brackets, but Mail stores the id without them, so every scoped resolve fell through to the broad scan and hit the timeout. Now bracket-stripped — a write on a 210k-message mailbox resolves in ~2s.
• Compose/send was broken: recipients/attachments used .make() (raises -10024), the subject was dropped by make(withProperties) (blocking the send on a "no subject" dialog), and the account argument was ignored (sent from the default account). Fixed and verified end-to-end: compose+send with an attachment now delivers from the requested account with the file attached.

Install

pipx install cobos-apple-mail-mcp        # or: pip install "cobos-apple-mail-mcp[attachments]"
apple-mail-mcp init && apple-mail-mcp index build

Single file (run with the matching Python minor version — see the wiki):

curl -LO https://github.com/ErnestoCobos/cobos-apple-mail-mcp/releases/download/v0.2.0/apple-mail-mcp.pyz
python3.12 apple-mail-mcp.pyz init

Artifacts (built with Python 3.12)

File	Contents	Size
apple-mail-mcp.pyz	Core server	17 MB
apple-mail-mcp-full.pyz	Core + [watch] + [semantic] + [attachments]	23 MB
SHA256SUMS.txt	Checksums	—

Requirements: macOS + Apple Mail, Python 3.10+, Full Disk Access (indexing) and Automation (writes). No credentials handled — Mail.app does its own auth. Full docs: README · Wiki.

v0.1.0

cobos-apple-mail-mcp v0.1.0

Unified Apple Mail MCP server: fast on-disk reads/search (Envelope Index + .emlx + FTS5) and
complete AppleScript/JXA writes, bridged by canonical RFC822 Message-ID resolution with mandatory
read-back verification, behind one safety layer (--read-only, batch caps, dry-run, confirm,
honest undo).

Highlights

• 25 MCP tools covering reading, keyword/hybrid search, threading, triage/analytics, and full
  write access (compose/reply/forward/drafts/move/status/mailboxes/trash/attachments).
• Optional Apple NaturalLanguage semantic search ([semantic] extra) — no model download,
  verified with genuine semantic (not keyword) ranking.
• JWZ email threading, awaiting-reply/needs-response triage, 5 bundled recipes exposed as MCP
  prompts.
• Never-hang design: bounded subprocess timeouts with process-group kill, immutable SQLite reads,
  async server, bounded broad scans.
• Verified end-to-end against a real, live 210,152-message / 7-account mailbox (index build,
  search, overview, triage, threading) — not just synthetic test fixtures. This surfaced and
  fixed a real crash (malformed real-world headers producing text SQLite couldn't store — see
  the on-disk format wiki page)
  and corrected an over-broad "sub-100ms search at any scale" claim (true for realistic queries —
  9-20ms measured — not for a deliberately non-selective single-word query matching 39% of the
  mailbox).

Install

pipx install cobos-apple-mail-mcp
apple-mail-mcp init
apple-mail-mcp index build

Or grab a single self-contained file below (see Single-file packaging
for the required matching-Python-version caveat):

curl -LO https://github.com/ErnestoCobos/cobos-apple-mail-mcp/releases/download/v0.1.0/apple-mail-mcp.pyz
python3.12 apple-mail-mcp.pyz init

Artifacts

File	Contents	Size
apple-mail-mcp.pyz	Core server	17.4 MB
apple-mail-mcp-full.pyz	Core + [watch] + [semantic]	24.3 MB
SHA256SUMS.txt	Checksums for both	—

Both were built with Python 3.12 — run them with python3.12, not a different minor version (see
the wiki page above for why).

Requirements

macOS with Apple Mail configured, Python 3.10+. Full Disk Access (indexing) and Automation
(writes) permissions — see Permissions & troubleshooting.

Full docs: README ·
Wiki