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

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)

Tool	Purpose
mail_health_check	Verify server, platform, Mail store discovery
mail_permissions_check	Diagnose Full Disk Access
mail_list_accounts	List account coverage
mail_list_mailboxes	List mailboxes/folders
mail_search_messages	Search local metadata (no body read)
mail_read_message	Read a selected downloaded message
mail_read_thread	Read a bounded local thread
mail_list_attachments	List attachment metadata

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