Skip to content

v0.2.0

Choose a tag to compare

View all tags
@ErnestoCobos ErnestoCobos released this 01 Jul 04:20
· 23 commits to main since this release
v0.2.0
6495501

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.

Assets 5
Loading