mcpField
A
apple-mail-search

apple-mail-search

github.com/nicolaischmidProductivity284 installsUpdated 39w ago
Repository

About apple-mail-search

A command-line skill for searching and reading messages in Apple Mail’s local database. It supports filtering by sender, subject, dates, account, and mailbox without opening Mail.app.

Key features

  1. 01List accounts and mailboxes
  2. 02Search by subject, sender, or date
  3. 03Filter by account and mailbox
  4. 04Show recent or unread messages
  5. 05Read message content and dump by date

Use cases

  1. 01Find an email by sender or subject
  2. 02Review recent or flagged messages
  3. 03Read a specific message without opening Mail.app
  4. 04Export messages from a chosen date

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nicolaischmid/agent-skills --skill apple-mail-search

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

Bundled filesREADME.mdscripts/mail-search

Details

From the project README

Apple Mail Search

Direct SQL search against Apple Mail's Envelope Index database. Queries complete in under 0.5 seconds against all mail accounts.

When to use

  • You need to find emails by subject, sender, or date.
  • You want to list available mailboxes and accounts.
  • You need fast search without opening Mail.app.
  • You want to read email content from specific messages.

How it works

  1. Reads Apple Mail's Envelope Index SQLite database at ~/Library/Mail/V10/MailData/
  2. Joins messages with subjects, addresses, and mailboxes tables
  3. Returns metadata (subject, sender, date, mailbox) for matching messages
  4. Can retrieve full email content from .emlx files when needed

The database is always up-to-date as Mail.app writes to it in real-time.

Usage

# List all configured mail accounts
mail-search accounts

# List all mailboxes for an account
mail-search mailboxes --account "Wasc.me"

# Search by subject (case-insensitive, substring match)
mail-search search --subject "invoice"

# Search by sender
mail-search search --sender "github.com"

# Search in message body/preview
mail-search search --body "tracking number"

# Search within a specific account
mail-search search --subject "receipt" --account "iCloud"

# Search within a specific mailbox
mail-search search --subject "order" --mailbox "INBOX" --account "Wasc.me"

# Search by date range
mail-search search --subject "meeting" --after "2026-01-01" --before "2026-01-31"

# Limit results
mail-search search --sender "amazon" --limit 10

# Get recent messages
mail-search recent --limit 20

# Get recent messages from a specific account
mail-search recent --account "Wasc.me" --limit 10

# Read full content of a message by ID
mail-search read --id 329402

# Dump messages from a specific date
mail-search dump --date "2026-01-25"
Commands
CommandDescription
accountsList all configured mail accounts
mailboxesList mailboxes for an account
searchSearch messages by subject, sender, date
recentGet most recent messages
readRead full content of a specific message
dumpDump all messages from a specific date
Search Flags
FlagShortDescription
--subject <text>-sSearch in subject (case-insensitive substring)
--sender <text>-fSearch in sender address or name
--body <text>-bSearch in message body/preview (uses summaries)
--account <name>-aFilter to specific account
--mailbox <name>-mFilter to specific mailbox
--after <YYYY-MM-DD>Messages received after this date
--before <YYYY-MM-DD>Messages received before this date
--limit <n>-nMaximum results (default: 50)
--unread-uOnly show unread messages
--flagged-FOnly show flagged messages
Output Format
[329402] 2026-01-25 22:39 | [email protected] (vercel[bot])
        [shadcn-ui/ui] fix: copy button copies full code even when collapsed (PR #9451)
        Mailbox: Wasc.me/INBOX
  • First line: Message ID, date/time, sender
  • Second line: Subject
  • Third line: Account/Mailbox path

Performance

OperationTime
List accounts<0.1s
Search (any criteria)<0.3s
Read message content<0.2s

Database Schema

Key tables in Envelope Index:

  • messages - Message metadata (sender, subject refs, dates, flags)
  • subjects - Subject text (normalized)
  • addresses - Email addresses and display names
  • mailboxes - Mailbox URLs (account/folder structure)
  • summaries - Email preview snippets

Security Considerations

  • Read-only access to Mail's SQLite database
  • No data is modified or written
  • No network requests; all local operations
  • Searches happen locally; nothing leaves your machine

Troubleshooting

  • "Database not found": Ensure Apple Mail has been opened at least once
  • "Database is locked": Mail.app may be syncing; retry in a moment
  • Empty results: Check account/mailbox names with accounts and mailboxes commands
  • Missing message content: Some messages may be partially downloaded (IMAP); full content requires Mail.app to download

Limitations

  • Body search uses the summaries table (email previews), not full message content
  • For full-text body search, use read --id to get complete message content
  • Attachments are not searchable via this tool
  • Deleted messages (in Trash) may still appear until permanently deleted

Comments

Markdown supported