mcpField
A
apple-mail

apple-mail

github.com/mitsuhikoProductivity3.2k252 installsUpdated 5w ago
Repository

About apple-mail

A skill for searching, reading, and extracting attachments from Apple Mail's local storage on macOS. Its bash script reads the SQLite envelope index and `.emlx` files without modifying mail data.

Key features

  1. 01Search by sender, recipient, and subject
  2. 02Filter by date, mailbox, or status
  3. 03Read messages as RFC822
  4. 04Extract attachments to a temporary directory
  5. 05Read-only access to local mail

Use cases

  1. 01Find emails matching search criteria
  2. 02Read a message and inspect its metadata
  3. 03Save attachments from a message

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/mitsuhiko/agent-stuff --skill apple-mail

After installing, type/apple-mailin Claude Code to confirm it loaded.

Bundled filesapple-mail.sh

Details

From the project README

Apple Mail Skill

Search, read, and extract attachments from Apple Mail's local storage on macOS.

Tool

apple-mail.sh — a bash script that queries the Apple Mail SQLite envelope index and reads .emlx files from disk. Read-only — it never modifies mail data.

Quick Reference

TOOL=~/Development/agent-stuff/skills/apple-mail/apple-mail.sh

# Search emails
$TOOL search --from "peter@" --subject "dinner" --limit 5
$TOOL search --after 2026-02-01 --has-attachment
$TOOL search --body "invoice" --mailbox "INBOX" --unread
$TOOL search --to "armin@" --before 2025-12-31

# Show message metadata, recipients, attachments, and summary
$TOOL info 783660

# Read the raw RFC822 email (headers + body)
$TOOL read 783660

# Extract attachments to a temp directory (prints the path)
$TOOL attachment 783660                          # all attachments
$TOOL attachment 783660 "Rechnung.pdf"           # specific file

# List all mailboxes with counts
$TOOL mailboxes

Search Options

FlagDescription
--from <addr>Sender address substring
--to <addr>Recipient address substring
--subject <text>Subject substring
--body <text>Body/summary text substring
--mailbox <name>Mailbox URL substring (e.g. INBOX, Sent, Trash)
--after <YYYY-MM-DD>Received after date
--before <YYYY-MM-DD>Received before date
--unreadOnly unread messages
--flaggedOnly flagged messages
--has-attachmentOnly messages with attachments
--limit <n>Max results (default: 20)

Output Format

  • search returns pipe-delimited table with header row: id|sender|sender_name|subject|received|status|flagged|mailbox|attachments
  • info returns structured metadata sections
  • read outputs raw RFC822 email to stdout
  • attachment prints the temp directory path to stdout, file listing to stderr

Notes

  • Message IDs are Apple Mail internal ROWIDs (integers), shown in the id column
  • .partial.emlx files contain headers only (body not downloaded); read warns about this
  • Attachments are copied to a temp directory under /tmp/; clean up when done
  • The body search queries the summaries table (Apple Mail's plaintext preview), not the full email body
  • Mailbox URLs are percent-encoded (e.g., %5BGmail%5D = [Gmail], %20 = space)
  • Deleted messages are excluded from search by default

Comments

Markdown supported