Rusty Apple Mail

TL;DR

Read-only MCP server for Apple Mail on macOS. Also works as a CLI tool.

Need an AI agent to safely search and read Apple Mail on your Mac? This project provides a clean, read-only MCP layer over Apple Mail’s native storage — fast index-based searches, on‑demand body hydration from .emlx, and zero write access.

It gives an LLM or AI agent fast local access to Apple Mail metadata, message bodies, and attachment text without AppleScript and without IMAP/POP/EWS network calls.

Why this matters

Apple Mail already contains the data an agent needs, but it is buried in a local SQLite index and scattered .emlx files.

This project exposes that storage through a small, intent-driven MCP interface so an agent can:

• locate messages by subject, date range, sender, participant, mailbox, or account;
• fetch a full message including metadata, recipients, body, and attachment summary;
• extract readable text from supported attachments;
• operate completely locally and read-only.

In practice, it empowers AI workflows to search and read your mail archive safely and quickly, without relying on Mail.app automation like AppleScript (which damn slow and throws timeouts regularly) or network protocols.

What the server can do

The current tool set is intentionally compact:

Tool	What it does
search_messages	Search by subject, dates, sender, participant, account, or mailbox
list_accounts	Discover account identifiers; set include_mailboxes=true for combined account+mailbox discovery
get_message	Read one message through a bounded content window; recipients omitted by default (include_recipients=true to include)
get_attachment_content	Extract readable attachment text through a bounded content window

Installation

Prerequisites

• macOS
• Apple Mail installed and synced at least once
• Rust toolchain (rustup, cargo)

Note — macOS Full Disk Access required

Apple Mail's data directory (~/Library/Mail) is protected by macOS TCC (Transparency, Consent, and Control). The MCP server process must have Full Disk Access to read the Envelope Index database.

Grant Full Disk Access to the application that runs the MCP server:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click + and add the application (e.g., your terminal emulator, VS Code, Zed, Cursor)
3. Ensure the toggle is enabled

Without this, the server will fail with SQLite error: unable to open database file even though the file exists.

Build from source

cargo build --release

Install locally

cargo install --path .

This installs the binary under the name rusty_apple_mail_mcp.

Running the server

The server supports two operating modes:

MCP Mode (default)

In MCP mode, the server communicates via stdin/stdout using the Model Context Protocol. This is the primary mode for integration with AI agents, Claude Code, VS Code, and other MCP-compatible clients.

To start from source:

cargo run --release

Or with the installed binary:

rusty_apple_mail_mcp

For interactive experimentation, use the MCP Inspector:

npx -y @modelcontextprotocol/inspector ./target/release/rusty_apple_mail_mcp

CLI Mode

In CLI mode, you can run individual commands directly from the terminal. This is useful for:

• Scripting — automation of mail search tasks in shell scripts
• Debugging — quick testing without setting up an MCP client
• Integration — piping results to other command-line tools
• One-off queries — when you need a quick answer without starting a persistent server

Usage

# List all accounts
rusty_apple_mail_mcp list-accounts
rusty_apple_mail_mcp list-accounts --include-mailboxes

# Search messages
rusty_apple_mail_mcp search --subject-query "invoice"
rusty_apple_mail_mcp search --sender "[email protected]" --limit 10
rusty_apple_mail_mcp search --date-from "2024-01-01" --date-to "2024-12-31"
rusty_apple_mail_mcp search --mailbox "INBOX" --include-body-preview

# Get a specific message
rusty_apple_mail_mcp get-message --message-id "12345"
rusty_apple_mail_mcp get-message --message-id "12345" --include-recipients
rusty_apple_mail_mcp get-message --message-id "12345" --offset 8192 --source-revision "..."

# Get attachment content
rusty_apple_mail_mcp get-attachment --message-id "12345" --attachment-id "12345:0"
rusty_apple_mail_mcp get-attachment --message-id "12345" --attachment-id "12345:0" --offset 8192 --source-revision "..."

CLI Configuration

CLI mode supports the same configuration options as MCP mode:

Option	Env Variable	Description
--mail-directory	APPLE_MAIL_DIR	Mail data directory (default: ~/Library/Mail)
--mail-version	APPLE_MAIL_VERSION	Envelope Index version (default: V10)
--scope-account	APPLE_MAIL_ACCOUNT	Startup Scope selector(s); comma-separated account names, emails, or IDs (see Account scoping). The legacy top-level --account spelling is a compatibility alias; search --account remains a per-call Filter.

Example:

rusty_apple_mail_mcp --mail-directory ~/Library/Mail --mail-version V10 search --subject-query "meeting"

Or with environment variables:

export APPLE_MAIL_DIR="$HOME/Library/Mail"
export APPLE_MAIL_VERSION="V10"
rusty_apple_mail_mcp list-accounts

CLI vs MCP: Key Differences

Feature	MCP Mode	CLI Mode
Protocol	stdin/stdout (MCP)	Direct command execution
Use case	AI agents, IDE integration	Scripting, debugging, one-off queries
Persistent process	Yes	No (per-command spawn)
Output format	JSON-RPC messages	Compact JSON by default; --pretty opts into formatted JSON
Real-time streaming	Yes	No (batch output)
Error handling	MCP error codes	Exit codes + stderr

When to Use Each Mode

Use MCP mode when:

• Integrating with Claude Code, VS Code, or other MCP clients
• Building AI-powered workflows that need to make multiple queries
• You need a persistent server process
• Your client already speaks MCP

Use CLI mode when:

• Writing shell scripts or automation
• Quick debugging and testing
• Piping results to other tools (jq, grep, etc.)
• Making single queries without overhead of starting a server
• Running from cron jobs or CI/CD pipelines

Example CLI pipeline:

# Find all messages from sender, extract subjects, save to file
rusty_apple_mail_mcp search --sender "[email protected]" | \
  jq -r '.messages[].subject' > ~/meeting-subjects.txt

# Count messages from last month
rusty_apple_mail_mcp search --date-from "2024-12-01" --date-to "2024-12-31" | \
  jq '.messages | length'

Configuration

The server supports configuration via environment variables, CLI flags, and a YAML config file. Values are resolved with this priority chain:

CLI flags > environment variables > config.yaml > defaults

Config file locations

The server looks for config.yaml in two locations (first found wins):

1. Next to the binary — same directory as the executable
2. Home config — ~/.config/rusty_apple_mail_mcp/config.yaml

Copy config.example.yaml to one of these locations and fill in your values:

cp config.example.yaml ~/.config/rusty_apple_mail_mcp/config.yaml

Configuration fields

Config Key	Env Variable	CLI Flag	Default	Description
apple_mail_dir	APPLE_MAIL_DIR	--mail-directory	~/Library/Mail	Root folder of the Mail data
apple_mail_version	APPLE_MAIL_VERSION	--mail-version	V10	Envelope Index version subdirectory
apple_mail_account	APPLE_MAIL_ACCOUNT	--scope-account	unset	Startup Scope selector(s); legacy top-level --account remains a compatibility alias
log_level	APPLE_MAIL_LOG_LEVEL	—	warn	Log level; RUST_LOG takes precedence

Priority chain examples

# ~/.config/rusty_apple_mail_mcp/config.yaml
apple_mail_dir: "~/Library/Mail"
apple_mail_version: "V10"
apple_mail_account: "Work Email"
log_level: "info"

# Environment variables override config.yaml
export APPLE_MAIL_VERSION="V9"

# CLI flags override everything
rusty_apple_mail_mcp --mail-version V8 search --subject-query "invoice"

Security note

config.yaml may contain account selectors and other configuration. It is added to .gitignore to prevent accidental commits. Never commit real configuration to version control.

RUST_LOG values

The server reads RUST_LOG through tracing_subscriber::EnvFilter, so it accepts the usual Rust tracing filter syntax.

Common values:

• error — only errors
• warn — warnings and errors
• info — startup and high-level operational logs
• debug — includes per-request debug logs
• trace — very verbose tracing
• off — disables logging

You can also scope logs per module/crate:

• rusty_apple_mail_mcp=debug
• rusty_apple_mail_mcp=trace,rusqlite=warn
• info,rmcp=warn

When RUST_LOG enables debug for this crate, search_messages logs timing breakdowns to stderr, including:

• total matched rows
• SQL query time
• metadata hydration time from SQLite
• body preview fallback time
• total request time

Account scoping

If APPLE_MAIL_ACCOUNT is set, the server resolves each selector through macOS ~/Library/Accounts/Accounts4.sqlite and then restricts all tools to the matched Mail account IDs.

Discovering account selectors

Run list_accounts without scoping first — it shows all available accounts with their names and emails:

rusty_apple_mail_mcp list-accounts

Example output:

{
  "accounts": [
    {
      "account_id": "ews://7FD31F78-81BB-4EAF-8955-9EC689C83920",
      "account_type": "ews",
      "account_name": "Exchange",
      "email": "[email protected]",
      "mailbox_count": 74,
      "message_count": 69291
    },
    {
      "account_id": "imap://CD5254B8-6B26-4ABA-B175-C8C984164B87",
      "account_type": "imap",
      "email": "[email protected]",
      "mailbox_count": 150,
      "message_count": 39494
    }
  ]
}

Use account_name, email, or account_id as selectors.

Selector format

Selector type	Example	When to use
Account name	Exchange	Human-friendly, from macOS Accounts settings
Email address	[email protected]	Unique, works across protocols
Account ID	ews://UUID	Always available in list_accounts output

Multiple selectors are comma-separated:

APPLE_MAIL_ACCOUNT="Exchange,[email protected]"

How matching works

• Matching is case-insensitive and trims whitespace.
• Startup fails fast if a selector matches zero accounts (typo) or multiple accounts (ambiguous).
• Accounts not registered in macOS Accounts settings cannot be selected by name or email — use their account_id instead.

VS Code integration

Example minimum .vscode/mcp.json configuration:

{
    "servers": {
        "mail_mcp": {
            "command": "rusty_apple_mail_mcp",
            "args": [],
            "env": {
                "APPLE_MAIL_DIR": "/Users/your-user/Library/Mail",
                "APPLE_MAIL_VERSION": "V10",
                "APPLE_MAIL_ACCOUNT": "Work Email",
                "RUST_LOG": "warn"
            }
        }
    }
}

Usage

Typical usage pattern:

1. Call list_accounts (optionally with include_mailboxes=true) to discover accounts and mailboxes.
2. Use search_messages to build a shortlist of candidates.
3. Call get_message to fetch the full message you care about.
4. Use get_attachment_content when you need the text of a particular attachment.

Token efficiency

The server is optimized to minimize token consumption:

• Compact tool descriptions — routing hints live in ServerInfo.instructions (loaded once), not repeated per-tool on every request.
• HTML → plain text — HTML email bodies are converted to clean text via DOM parsing (using scraper), typically 10–20× smaller than raw HTML.
• Explicit completed outcomes — successful MCP/tool payloads carry outcome: "success", outcome: "partial", or outcome: "not_found"; protocol errors stay native errors.
• Recipients omitted by default — get_message skips To/CC lists unless include_recipients=true.
• Compact dates — ISO 8601 without seconds (2024-09-15T00:00Z).
• has_body removed — always true for indexed messages; no longer wasting tokens.

Sample search request

{
    "subject_query": "invoice",
    "account": "imap://ACCOUNT-ID",
    "limit": 10
}

Sample message retrieval

{
    "message_id": "12345",
    "include_body": true,
    "include_attachments_summary": true,
    "include_recipients": false,
    "offset": 0,
    "limit": 8192
}

include_recipients defaults to false — set it to true when you need the To/CC lists (saves tokens on corporate mail with 50+ recipients). If a response returns outcome: "partial", continue with the returned window.next_offset and window.source_revision.

Combined account + mailbox discovery

Use include_mailboxes=true to get accounts with their mailboxes grouped in a single call:

{
    "include_mailboxes": true
}

This returns accounts with their mailboxes grouped, saving one round-trip.

How it works

The server draws from two local sources:

• Envelope Index – the SQLite database Apple Mail uses as a metadata index and relationship store
• .emlx files – the canonical bodies and attachments for individual messages

Search queries hit the lightweight index, keeping them fast; bodies and attachments are loaded on-demand from the .emlx files.

Development

Handy commands while working on the codebase:

cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo doc --no-deps

Limitations

• macOS only
• read-only access only
• stdio transport only
• requires Apple Mail storage to be present on disk
• some binary attachment formats may yield metadata instead of extracted text