Apple Mail MCP Server

A lightweight, read-only MCP server for Apple Mail on macOS. Reads directly from Mail's local SQLite database and .emlx files — no AppleScript needed for reading. Designed for large mailboxes (tested with 290K+ messages across multiple accounts).

Features

• Fast search — SQL-level filtering pushed down to SQLite, not Python-side iteration
• Pagination — offset / limit support for large result sets
• Deterministic file lookup — .emlx files located via a cached directory map, no rglob per message
• Read-only — no send capability, no AppleScript, minimal attack surface
• Minimal dependencies — just the mcp SDK and Python stdlib
• Multi-account support — works with iCloud (IMAP), Exchange (EWS), Gmail, and other accounts configured in Mail.app

Tools

Tool	Description
list_accounts	List configured mail accounts
list_mailboxes	List all folders with message counts and unread counts
search_emails	Search / filter by sender, subject, date range, mailbox, read status. Paginated.
read_email	Fetch full content of a single email by ID (including To, CC, body)

Installation

With uvx (recommended)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/BastianZim/apple-mail-mcp",
        "apple-mail-mcp"
      ]
    }
  }
}

Restart Claude Desktop after saving.

From source

git clone https://github.com/BastianZim/apple-mail-mcp
cd apple-mail-mcp
uv run apple-mail-mcp

Requirements

• macOS 10.15+ (Catalina or later)
• Python 3.10+
• Apple Mail configured with at least one account
• Full Disk Access for the process running the server (see below)

macOS permissions

Apple Mail's database lives in ~/Library/Mail/, which macOS protects. You must grant Full Disk Access to the process that runs the MCP server.

For Claude Desktop using uvx:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click the + button
3. Add the uvx binary (typically at /opt/homebrew/bin/uvx)
4. Restart Claude Desktop

Without this, the server will fail with unable to open database file.

Tip: To find where uvx lives on your system, run which uvx in your terminal.

How it works

Apple Mail stores email metadata in a SQLite database at ~/Library/Mail/V10/MailData/Envelope Index and message bodies in .emlx files inside .mbox directories.

This server:

1. Opens the SQLite DB read-only for fast, indexed queries.
2. Caches the list of .mbox/Messages/ directories at startup (typically 10–50 dirs regardless of email count).
3. Resolves .emlx files by message ID with simple stat() calls — no filesystem search.

search_emails parameters

All filters are AND-combined.

Parameter	Type	Description
query	str	Free-text across sender + subject
sender	str	Substring match on address or display name
subject	str	Substring match on subject line
mailbox_id	int	Restrict to a mailbox (from list_mailboxes)
unread_only	bool	Only unread messages
date_from	str	ISO date, inclusive start (2025-01-01)
date_to	str	ISO date, inclusive end (2025-12-31)
limit	int	Max results, default 20, max 200
offset	int	Pagination offset

License

MIT