Skip to content

v0.1.0

Choose a tag to compare

View all tags
@ErnestoCobos ErnestoCobos released this 01 Jul 00:28
· 36 commits to main since this release
v0.1.0
69e1015

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

Assets 5
Loading