Apple Mail Read-Only MCP

A local MCP server for searching and reading downloaded Apple Mail data without changing mail state. It can run with any compatible MCP client and includes optional Codex plugin packaging.

Features

• List Apple Mail accounts and mailboxes

• Search local metadata (subject, sender, date) without reading bodies

• Read selected downloaded message bodies with strict size limits

• Read bounded local threads/conversations

• List attachment metadata only (no export)

• Full Disk Access diagnostics

Related MCP server: local-apple-data

Requirements

• macOS

• Python 3.11+

• Apple Mail configured locally

• Full Disk Access may be required for the launcher process

Quick Start

# Run the MCP server
bash scripts/run_mcp.sh

# Run tests
python3 -m unittest discover -s tests -v

# Static security check
python3 scripts/doctor.py --static

# Live smoke test (opt-in)
APPLE_MAIL_READONLY_RUN_LIVE=1 python3 scripts/smoke_test.py

MCP Tools (v0.1)

Non-Goals

This server will never:

• Send email

• Create drafts

• Reply/forward

• Move, delete, archive, mark read/unread, flag

• Export/open/download attachments

• Run arbitrary scripts

• Update itself

Installation

Run scripts/run_mcp.sh from any MCP client that supports stdio servers. See docs/codex-install.md for Codex plugin installation instructions.

Privacy and Security

Mail content stays on the local machine. The server opens the Apple Mail index in SQLite read-only mode, registers no write-capable tools, makes no mail-provider API calls, and never exports attachment contents. See docs/security-model.md for the complete guarantees and limitations.

License

MIT