Apple Mail MCP

io.github.imdinuPublished by GitHub account imdinuv0.5.0Updated Oct 24, 2026

Apple Mail MCP server with full-coverage FTS5 body search, reliable on large mailboxes.

VerifiedSTDIODesktop onlyFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

Local MCP server that lets an assistant read, search and extract content from Apple Mail on a Mac, including full-mailbox body search via an FTS5 index.

What you can do
  • List accounts and mailboxes
  • Fetch emails by filter (all, unread, flagged, today, last 7 days) or by message ID with full content and attachments
  • Search across all, subject, sender, body or attachments, with date bounds and highlighting
  • Extract links and attachment content from a specific message
When to use it
Useful when you want an assistant to work with a Mac's Apple Mail: finding messages in a large mailbox, reading a specific email, or pulling links and attachments out of it. Aimed at users whose mail volume makes AppleScript-based servers time out.
Requirements
Runs locally on macOS as a PyPI package (apple-mail-mcp) launched via uvx, pipx or a Claude plugin/bundle. Apple Mail must be set up, and the launching app needs Full Disk Access so the search index can be built and kept fresh. Optional configuration via a config file or APPLE_MAIL_* environment variables.
Before you install
Requires granting Full Disk Access to the app that launches it, which gives that app broad access to local data. The server reads the entire local mail store, including message bodies and attachments, and passes that content to the assistant and its model. The --watch mode keeps an index running in the background.

Installation

In SourceWeft

  1. Open Apple Mail MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Apple Mail MCP

[Apple Mail MCP — Full-coverage FTS5 body search]

[Python 3.11+] [License: GPL v3] [macOS] [MCP] [Code style: ruff] [CI]

The only Apple Mail MCP server with full-coverage body search — reliable on large mailboxes where AppleScript-based servers timeout. 8 tools for reading, searching, and extracting email content.

Read the docs for the full guide.

Quick Start

Claude Code (plugin)

bash
claude plugin marketplace add imdinu/apple-mail-mcpclaude plugin install apple-mail@imdinu

Claude Desktop (one-click bundle)

Download apple-mail-mcp-<version>.mcpb from the latest release and double-click it.

Both the plugin and the bundle run the released PyPI package via a thin launcher (uvx → pipx → private venv, whichever is available) — no vendored code, identical behavior to a manual install. They start the server with --watch; grant Full Disk Access to the launching app (Claude Code / Claude Desktop) so the index stays fresh.

Any MCP client

bash
pipx install apple-mail-mcp

Add to your MCP client:

json
{  "mcpServers": {    "mail": {      "command": "apple-mail-mcp"    }  }}

Build the Search Index (Recommended)

bash
# Requires Full Disk Access for Terminal# System Settings → Privacy & Security → Full Disk Access → Add Terminal
apple-mail-mcp index --verbose

Configure (Optional)

bash
apple-mail-mcp init   # writes ~/.apple-mail-mcp/config.toml

Writes a commented config file you can edit to set defaults like your primary account or mailbox. Every key has a matching APPLE_MAIL_* env var if you prefer environment-based config. See Configuration for the full schema and precedence rules.

Tools

ToolPurpose
list_accounts()List email accounts
list_mailboxes(account?)List mailboxes
get_emails(filter?, limit?)Get emails — all, unread, flagged, today, last_7_days
get_email(message_id)Get single email with full content + attachments
search(query, scope?, before?, after?, highlight?)Search — all, subject, sender, body, attachments
get_email_links(message_id)Extract links from an email
get_email_attachment(message_id, filename)Extract attachment content
get_attachment(message_id, filename)Deprecated — use get_email_attachment()

Performance

Tested against 6 other Apple Mail MCP servers on a real ~73K-message mailbox:

  • Only server with full-coverage body search. Most competitors don't support body search at all; the one that does (BastianZim) live-scans only the 5000 most recent messages — silent miss on anything older. Our FTS5 index covers the entire mailbox.
  • ~3ms single email fetch via disk-first .emlx reading (no JXA round-trip).
  • ~1ms list_accounts and ~5ms 50-email listing via direct Envelope-Index SQLite reads (0.4+) — same path BastianZim/rusty/pl-lyfx use, with JXA as the correctness fallback.
  • ~7ms subject search via FTS5 — competitive with native Rust on the same operation.
  • Reliable across all 6 benchmarked operations on a 73K mailbox; AppleScript-based servers timeout, throw syntax errors, or skip operations they don't support.

[Capability Matrix]

Configuration

Apple Mail MCP works out of the box. To customize defaults, run apple-mail-mcp init to generate a config.toml template — or use the matching APPLE_MAIL_* environment variables. See the Configuration docs for the full schema and the CLI > env > file > default precedence.

Per-client env overrides via the MCP client's launch config also work:

json
{  "mcpServers": {    "mail": {      "command": "apple-mail-mcp",      "args": ["--watch"],      "env": {        "APPLE_MAIL_DEFAULT_ACCOUNT": "Work"      }    }  }}

CLI Usage

All tools are also available as standalone CLI commands (no MCP server needed):

bash
apple-mail-mcp search "quarterly report" --scope subjectapple-mail-mcp search "invoice" --after 2026-01-01 --limit 10apple-mail-mcp read 12345apple-mail-mcp emails --filter unread --limit 10apple-mail-mcp accountsapple-mail-mcp mailboxes --account Workapple-mail-mcp extract 12345 invoice.pdf

All commands output JSON. Generate a Claude Code skill for CLI-based access:

bash
apple-mail-mcp integrate claude > ~/.claude/skills/apple-mail.md

Development

bash
git clone https://github.com/imdinu/apple-mail-mcpcd apple-mail-mcpuv syncuv run ruff check src/uv run pytest

License

GPL-3.0-or-later

Source: README.md at commit 0398b86

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts