get_attachment
DEPRECATED: Use get_email_attachment() or get_email_links().
Extract resources from an email: attachments or links. Delegates to get_email_links (filename omitted) or get_email_attachment (filename provided).
LABSCO SUMMARY
Body search that covers the whole mailbox, not the last few thousand messages.
On a large mail store the useful question is usually "find the message where someone mentioned X", and that only works if the index covers everything — which is why the setup step that matters is granting Full Disk Access and building the index, not the install itself. Everything here reads: there is no send, no reply and no filing, so it fits research and retrieval rather than inbox management.
What it is
A read-only reader for Apple Mail on macOS. It builds an FTS5 full-text index over the local mail store and reads .emlx files and the Envelope Index directly, with AppleScript kept as a fallback rather than the main path.
What you get
- search runs across every account and mailbox at once, scoped to all, subject, sender, body or attachments, with before and after date bounds, mailbox exclusions, paging and match highlighting
- Body search covers the whole mailbox through the index, rather than live-scanning only the most recent messages
- list_accounts and list_mailboxes enumerate what exists; get_emails lists one mailbox with filters for all, unread, flagged, today or last_7_days
- get_email fetches a single message with its full content, and finds it across accounts from the message id alone — account and mailbox are hints, not requirements
- get_email_links extracts an email's hyperlinks, deduplicated with their anchor text, with mailto:, javascript: and long tracking URLs filtered out
- get_email_attachment parses the raw MIME structure and saves a file under ~/.apple-mail-mcp/attachments/, including inline images and S/MIME parts
- Defaults set once with apple-mail-mcp init, which writes a config.toml; every key has a matching APPLE_MAIL_ environment variable, and the client's launch config can override per client
Requirements
macOS with Apple Mail, and Python 3.11 or higher — installed with pipx install apple-mail-mcp and run as apple-mail-mcp. The search index is what makes body search and link extraction work: build it with apple-mail-mcp index, which needs Full Disk Access granted to Terminal under System Settings → Privacy & Security. Nothing leaves the machine and no account credentials are involved — it reads the local mail store. GPL v3.
Setup effort
Follow the published steps — pipx install apple-mail-mcp
USE CASES
01
Finding a message you only half remember
Search bodies across every account with a couple of specific keywords, narrowed by date if you know roughly when.
02
Pulling the attachment out of an old email
Find the message, then extract the file by name — it parses the raw MIME, so inline images and signed parts come out too.
03
Getting the real links out of a newsletter
Extract the hyperlinks with their anchor text, with tracking URLs and mailto: links already filtered out.
04
Catching up on one mailbox
List that mailbox filtered to unread, flagged, or the last seven days, and open the ones that matter in full.
05
Answering a question that spans several accounts
Search everywhere at once — work and personal — excluding the mailboxes that would only add noise.
8 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_email
Get a single email with full content.
Looks up the email across all accounts using a cascade strategy. Just pass the message_id — account/mailbox are optional hints that speed up lookup but are not required.
get_email_attachment
Extract a file attachment from an email and save to disk.
Saves the attachment under ~/.apple-mail-mcp/attachments/. Parses the raw MIME structure, so it works for all attachment types including inline images and S/MIME signatures.
Requires the search index.
get_email_links
Extract hyperlinks from an email's HTML content.
Filters out mailto:, javascript:, and long tracking URLs. Returns deduplicated links with their anchor text.
Requires the search index.
get_emails
Get emails from a specific mailbox with optional filtering.
Note: This tool lists emails from a single mailbox. To search across all mailboxes, use the search() tool instead.
list_accounts
List all configured email accounts in Apple Mail.
Returns: List of account dictionaries with 'name' and 'id' fields.
Example: >>> list_accounts() [{"name": "Work", "id": "abc123"}, {"name": "Personal", "id": "def456"}]
list_mailboxes
List all mailboxes for an email account.
search
Search emails across all accounts and mailboxes.
Uses full-text search index for fast results (~2ms). All scopes search across every account and mailbox unless filtered.
Query tips:
- Use 2-3 specific keywords, not full sentences
- Terms are AND-ed: "budget Q1" finds emails with BOTH words
- Use quotes for exact phrases: '"quarterly report"'
- Prefix search: "meet*" matches meeting, meetings, etc.
- The default scope "all" searches subject + sender + body together
BEFORE YOU INSTALL
What to know first
Tools you get
8 tools when we connected. get_attachment is deprecated; use get_email_attachment. Filter values such as unread, today or last_7_days are arguments to get_emails and search, not tools.
Requires
- pipx on PATH
- Python 3.11+
- macOS Ventura or later, with Apple Mail
Where it runs
All 4 documented setups run the server on your machine.
CONTEXT COST
Light Standing cost
Rated by the size of the 8 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
pipx install apple-mail-mcpGrant Terminal Full Disk Access: System Settings → Privacy & Security → Full Disk Access → add Terminal
TERMINAL
apple-mail-mcp index --verboseMCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp"
}
}
}Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp",
"env": {
"APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
}
}
}
}Any MCP client — watch mode
ANY MCP CLIENT — WATCH MODE · JSON
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp",
"args": [
"--watch"
],
"env": {
"APPLE_MAIL_DEFAULT_ACCOUNT": "Work"
}
}
}
}Any MCP client — default mailbox
ANY MCP CLIENT — DEFAULT MAILBOX · JSON
{
"mcpServers": {
"mail": {
"command": "apple-mail-mcp",
"env": {
"APPLE_MAIL_DEFAULT_ACCOUNT": "Work",
"APPLE_MAIL_DEFAULT_MAILBOX": "INBOX"
}
}
}
}
