v3.1.1

What's Changed

• fix: Update remaining PyPI package name reference in README
• chore: Remove stale artifacts, fix pyproject.toml for plugin/ layout
• chore: Add mcp-name verification string for official MCP Registry
• chore: Add server.json for MCP Registry schema validation

Full Changelog: v3.1.0...v3.1.1

v3.1.0 — Claude Code Plugin Distribution

What's New

Claude Code Plugin Support

Apple Mail MCP is now installable as a native Claude Code plugin — two commands, no manual setup:

claude plugin marketplace add patrickfreyer/apple-mail-mcp
claude plugin install apple-mail@apple-mail-mcp

This gets you:

• MCP Server — 24 email management tools, auto-registered
• /email-management slash command — instant access to email workflows
• Email Management Expert skill — auto-loaded with triage, inbox zero, and organization knowledge

Also Included

• MCPB (Claude Desktop) — apple-mail-mcp-v3.1.0.mcpb attached below
• PyPI — pip install mcp-apple-mail / uvx mcp-apple-mail

Repo Restructure

Plugin files now live in plugin/ subdirectory (marketplace convention). The repo root serves as the marketplace manifest. MCPB build script updated accordingly.

Full Changelog

v3.0.0...v3.1.0

v3.0.0 — Tool Consolidation & Reply Fix

What's New

Tool Consolidation (31 → 22 tools)

The API surface has been significantly simplified by merging overlapping tools:

• search_emails is now the single unified search tool — supports cross-account search (account=None), body text search (body_text), content preview (include_content + max_content_length), and all previous filter options (subject, sender, dates, attachments, read status, pagination)
• list_inbox_emails absorbs get_recent_emails — use max_emails + include_content params
• get_mailbox_unread_counts absorbs get_unread_count — use summary_only=True for per-account totals
• move_email absorbs bulk_move_emails + archive_emails — now supports sender, older_than_days, dry_run, only_read filters
• update_email_status absorbs update_email_status_by_ids + mark_emails — now supports message_ids and older_than_days params
• manage_trash absorbs delete_emails — now supports older_than_days and dry_run (default True)

Removed Tools

search_subjects, get_email_with_content, search_by_sender, search_email_content, get_recent_from_sender, search_all_accounts, get_newsletters, group_emails_by_subject_regex, get_recent_emails, get_unread_count, update_email_status_by_ids, archive_emails, mark_emails, delete_emails, bulk_move_emails

Fixes

• Reply/forward preserves email history — reply_to_email and forward_email no longer destroy the quoted original email thread (#32)
• FW: prefix stripping — get_email_thread no longer eats the first character of subjects starting with "FW: "
• Trimmed tool responses — compose/reply/forward confirmations no longer echo back the full email body, reducing token usage
• reply_to_email gains body_html param — HTML rendering still WIP (#31)

Breaking Changes

If you reference removed tool names in prompts or code, update to use the consolidated equivalents listed above. All capabilities are preserved — only the tool names changed.

Full Changelog

v2.2.0...v3.0.0

v2.2.0 — Rich Drafts, Read-Only Mode & i18n Fixes

What's New

Features

• Rich HTML email drafts — new create_rich_email_draft tool for composing formatted emails with HTML body content (#27 by @kkugot)
• Structured mail search — consolidated search_emails tool with structured field-level search parameters (#27 by @kkugot)
• Read-only mode — --read-only flag disables all email-sending tools for safe browsing/analysis (#26 by @aicayzer)

Fixes

• Unicode preservation — MCP output now preserves Cyrillic, CJK, Arabic, and all non-ASCII text instead of replacing with ? (#29 by @na-bal)
• Path validation on export — export_emails now validates save paths to prevent directory traversal into sensitive directories (#28 by @jzkelter)
• GitHub README — use HTML picture element for star history chart

Contributors

• @kkugot — rich drafts & structured search
• @aicayzer — read-only flag
• @na-bal — Unicode fix
• @jzkelter — path validation security fix

v2.1.1

Bug Fix

• fix: reply-to-all AppleScript syntax error — The reply command was missing and between with opening window and reply to all, causing a syntax error (-2741) for all reply-to-all operations (send, draft, open modes)

v2.1.0

What's New

Features

• HTML email support via NSPasteboard clipboard injection
• "Open" mode for compose, reply, and manage_drafts — review emails before sending
• Attachment support for compose and reply tools
• Consolidated search — 9 search tools unified into one search_emails with 16 filter parameters

Performance

• Native whose clause filtering replaces per-message iteration for dramatically faster searches
• Body search moved to native Mail.app filter (whose content contains) — eliminates timeouts on large mailboxes

Bug Fixes

• Reply AppleScript syntax errors — reply body now written to temp files instead of string interpolation, fixing errors with special characters (em dashes, curly quotes, colons, slashes)
• Open mode replies — switched from fragile per-character keystroke to clipboard paste
• Unicode line separator handling added to escape_applescript
• Manifest updated to reflect 27 tools (down from 35 after consolidation)

v2.0.0 — Security Hardening, Smart Inbox & Open Mode

Apple Mail MCP v2.0.0

35 tools (up from 26) with security hardening, smart inbox, and open-for-review mode.

Highlights

Open Mode for Email Composition

• compose_email(mode="open") — opens a compose window for review before sending
• reply_to_email(mode="open") — opens reply with native quoted original preserved
• manage_drafts(action="open") — opens an existing draft for editing

Security Hardening (Issue #19)

• Newline/tab escaping, confirm_empty for trash, filter requirements for destructive ops
• Path validation blocks sensitive directories, export capped at 1000, deps pinned

New Tools

• Bulk: mark_emails, delete_emails (dry_run default), bulk_move_emails
• Smart Inbox: get_awaiting_reply, get_needs_response, get_top_senders
• Infrastructure: create_mailbox, search_emails_advanced, archive_emails, JSON output

Performance

• whose clause filtering on search tools, locale-independent dates, system folder skipping

Attachments

• compose_email and reply_to_email accept attachments with path validation

Issues Closed

#1, #2, #3, #4, #5, #6, #7, #8, #9, #10, #11, #12, #19

Full Changelog: https://github.com/patrickfreyer/apple-mail-mcp/commits/v2.0.0