apple-mail-readonly-mcp
Allows searching and reading downloaded Apple Mail messages, including metadata and bodies, without modifying mail state. Provides tools for listing accounts, mailboxes, searching messages, reading messages and threads, and listing attachment metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@apple-mail-readonly-mcp search for emails from John about project updates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: apple-mail-mcp
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.pyMCP Tools (v0.1)
Tool | Purpose |
| Verify server, platform, Mail store discovery |
| Diagnose Full Disk Access |
| List account coverage |
| List mailboxes/folders |
| Search local metadata (no body read) |
| Read a selected downloaded message |
| Read a bounded local thread |
| 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
Available Tools
8 toolsmail_health_checkB
Verify server, platform, Mail store discovery, and read-only database access.
Inputs: include_paths.
mail_list_accountsC
List account UUID coverage from the local Envelope Index.
Inputs: limit, include_email_addresses.
mail_list_attachmentsA
List attachment metadata for one downloaded message. Does not export content.
Inputs: local_id, message_id.
mail_list_mailboxesB
List mailboxes/folders with optional filters.
Inputs: role, limit, query, account_uuid, +1 more.
mail_permissions_checkC
Diagnose Full Disk Access and optional settings guidance.
Inputs: open_full_disk_access.
mail_read_messageB
Read a selected downloaded message by local id or message id.
Inputs: local_id, message_id, body_format, include_body, +3 more.
mail_read_threadC
Read a bounded local thread/conversation.
Inputs: limit, local_id, message_id, body_format, +3 more.
mail_search_messagesA
Search local metadata newest-first. Does not read message bodies.
Inputs: limit, query, sender, date_to, +14 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct function: health check, account listing, attachment metadata, mailbox listing, permissions, message reading, thread reading, and search. No overlap in purpose.
All tools follow the 'mail_verb_noun' pattern with snake_case, e.g., mail_list_accounts, mail_read_message, providing strong predictability.
8 tools cover the core read-only operations on Apple Mail without being excessive or insufficient for the domain.
Covers health, permissions, account/mailbox listing, message/thread reading, search, and attachment metadata. Missing bulk message listing and attachment content export, but reasonable for read-only scope.
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Read, search and manage iCloud Mail, Calendar and Contacts from Claude and other MCP clients.
A MCP server for Gmail that lets you search, read, and draft emails and replies.
MCP server for MailTempo's public free temporary email inboxes.
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal MCP server for multi-account IMAP/SMTP email (iCloud + Gmail via app-specific passwords). Never marks mail read. Cross-folder search, idempotent sends, TLS verified.835 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceA read-only MCP server for Apple Mail on macOS that enables searching and reading emails directly from the local SQLite database, with fast SQL-level filtering and pagination.2MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that drives macOS Mail: read, search, send, organise.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Apple Mail that reads from Mail's SQLite store for fast queries and writes through Mail.app via AppleScript, enabling mailbox management, search, drafts, and message updates without sending mail.MIT