Apple Mail MCP
Integrates with Apple Mail on macOS to list accounts and mailboxes, search and read messages, create drafts and replies, send user-approved emails, and manage read, flag, and move status through local AppleScript automation.
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 MCP check my inbox and give me a daily briefing"
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 MCP
A local, stdio-based Model Context Protocol server for Apple Mail on macOS.
It talks only to the Apple Mail app already configured on the user's Mac. It does not need IMAP/SMTP passwords or open a network port.
Safety model
Mailbox and message tools are read-only by default.
create_draftopens an unsent, visible draft in Apple Mail.send_emailrequiresuser_approved: true. MCP clients should call it only after the user has approved the exact message.Message changes such as marking, flagging, and moving also require
user_approved: true.Dynamic content is passed to
osascriptas arguments, not interpolated into AppleScript source.Every write action has a local, metadata-only JSONL audit entry. Bodies and credentials are never written to that log.
The approval inbox and relationship context are stored only in the local JSON data store described below.
The MCP server itself is local. However, an MCP client may send tool results to an AI model or another service. Only connect clients and models you trust with mail content.
Related MCP server: mailmcp
Requirements
macOS with Apple Mail configured
Node.js 20+
Permission for the host application (for example Codex or Terminal) to control Mail under System Settings → Privacy & Security → Automation
Install
npm (recommended)
npm install -g @jakobf1/apple-mail-mcpThen configure your MCP client with the installed command:
{
"mcpServers": {
"apple-mail": {
"command": "apple-mail-mcp"
}
}
}From source
git clone https://github.com/YOUR_ACCOUNT/apple-mail-mcp.git
cd apple-mail-mcp
npm install
npm run buildAdd to an MCP client
If you installed from source rather than npm, use the compiled server over stdio:
{
"mcpServers": {
"apple-mail": {
"command": "node",
"args": ["/absolute/path/to/apple-mail-mcp/dist/index.js"]
}
}
}Restart the MCP client after saving its configuration. The first call will trigger the normal macOS automation permission prompt.
Optional sender policy
To allow sending only from specific configured Apple Mail addresses, configure a comma-separated allowlist when launching the server:
{
"env": {
"APPLE_MAIL_MCP_ALLOWED_SENDERS": "hello@example.com"
}
}Write-action audit metadata is stored locally at ~/.apple-mail-mcp/audit.jsonl by default. Set APPLE_MAIL_MCP_AUDIT_LOG to use another local path.
AI-first local workspace
The approval inbox and relationship context share a local JSON store at ~/.apple-mail-mcp/data.json by default. It contains queued draft bodies and the contact notes you intentionally save, so treat it as private mail data. Set APPLE_MAIL_MCP_DATA_STORE to use another local path.
APPLE_MAIL_MCP_DRY_RUN=true validates sends but prevents delivery. You can also enforce recipient restrictions with APPLE_MAIL_MCP_ALLOWED_RECIPIENTS, APPLE_MAIL_MCP_ALLOWED_RECIPIENT_DOMAINS, and a local time window such as APPLE_MAIL_MCP_SENDING_WINDOW=09:00-18:00.
Tools
Tool | What it does |
| Lists configured Apple Mail accounts and sender addresses. |
| Lists the top-level mailboxes in an account. |
| Returns inbox or mailbox summaries without message bodies. |
| Searches recent messages by sender or subject. |
| Reads one message body by id, with a configurable length limit. |
| Opens a visible, unsent outgoing message. |
| Hands an approved message to Apple Mail for delivery. |
| Opens a visible reply draft and preserves Apple Mail's reply recipient/subject handling. |
| Marks one approved message read or unread. |
| Flags or unflags one approved message. |
| Moves one approved message to another mailbox. |
| Reads the local metadata-only audit trail. |
| Inspects or validates the active send safeguards without delivery. |
| Stores proposed emails locally for human review. |
| Applies an explicitly approved queue decision. |
| Maintains private relationship notes, tone, commitments, and follow-up dates. |
| Combines a saved contact profile with recent inbox summaries. |
| Surfaces saved contacts that are due for a human-approved follow-up. |
| Switches between focused policies such as inbox zero, sales follow-up, support, and deep work. |
| Saves a user-approved local thread summary with its source message ids. |
| Combines unread messages, pending approvals, and due follow-ups into a safe daily action brief. |
Scope and non-goals
This project is local-only. It is not an SMTP server, does not manage credentials, and does not bypass macOS privacy prompts. It deliberately excludes deletion, attachment export, background scheduling, and automatic sending.
Publishing and registry metadata
The package is published as @jakobf1/apple-mail-mcp. Its MCP Registry identity is io.github.jakobfigur/apple-mail-mcp; see server.json for portable install metadata.
License
MIT
Available Tools
26 toolsapprove_queued_emailA
Turn one pending approval-queue item into a visible draft or send it. Only call after the user explicitly approved this exact item and delivery mode.
Inputs: item_id (required), delivery (required), user_approved (required).
create_draftA
Create a visible unsent draft in Apple Mail. Use this before sending whenever the user should review the message.
Inputs: to (required), text (required), subject (required), from.
create_reply_draftA
Open a visible reply draft for an existing message. The original message controls the recipient and subject. This does not send anything.
Inputs: text (required), account (required), message_id (required), mailbox.
discard_queued_emailA
Discard one pending approval-queue item. It will not affect Apple Mail. Only call after explicit user approval.
Inputs: item_id (required), user_approved (required).
get_audit_logA
Read recent local audit metadata for write actions. Email bodies are never stored in this log.
Inputs: limit.
get_contact_briefB
Build a local contact brief from saved relationship context and recent inbox summaries. Read-only; message bodies are excluded.
Inputs: email (required), account (required), limit, mailbox.
get_contact_contextB
Read the local relationship context for one email address. Read-only.
Inputs: email (required).
get_daily_briefingB
Create a read-only daily briefing from one inbox, the local approval queue, and saved follow-up dates. It never drafts, sends, or changes email.
Inputs: account (required), mailbox, unread_limit, follow_up_days.
get_messageA
Read one message body by its id. Use after list_messages or search_messages. Read-only.
Inputs: account (required), message_id (required), mailbox, max_body_characters.
get_send_policyA
Show the active local sending safeguards without exposing credentials. Read-only.
Inputs: no named parameters.
get_work_modeA
Show the active local AI-mail work mode and its allowed MCP actions. Read-only.
Inputs: no named parameters.
list_accountsA
List Apple Mail accounts and their configured sender addresses. Read-only.
Inputs: no named parameters.
list_approval_queueB
List proposed emails in the local approval inbox. Read-only.
Inputs: limit, status.
list_follow_up_radarA
List local contact records with a follow-up date due now or within a chosen horizon. Read-only; it never sends anything.
Inputs: within_days.
list_mailboxesA
List the top-level mailboxes in one Apple Mail account. Read-only.
Inputs: account (required).
list_messagesB
List message summaries from an Apple Mail mailbox. Read-only; bodies are not included.
Inputs: account (required), limit, mailbox, unread_only.
move_messageA
Move a message to another mailbox in the same account. Only call after the user explicitly approved this exact action.
Inputs: account (required), message_id (required), user_approved (required), destination_mailbox (required), +1 more.
preview_sendA
Validate a proposed email against the active local send policy without creating or sending anything. Read-only.
Inputs: to (required), text (required), subject (required), from.
queue_email_for_approvalA
Save a proposed email in the local approval inbox. It does not create a Mail draft or send anything.
Inputs: to (required), text (required), subject (required), from, +6 more.
save_contact_contextB
Save local relationship context for one contact. This does not modify Apple Mail or contact the person.
Inputs: email (required), user_approved (required), tone, notes, +7 more.
save_thread_summaryB
Save a local, user-approved summary of a selected contact thread, including the exact source message ids used. It does not modify Apple Mail.
Inputs: email (required), summary (required), user_approved (required), source_message_ids (required).
search_messagesA
Search recent messages by subject or sender in one mailbox. Read-only; bodies are not searched.
Inputs: query (required), account (required), limit, mailbox, +1 more.
send_emailA
Send an email using Apple Mail. Only call after the user explicitly approved this exact recipient, subject, and body.
Inputs: to (required), text (required), subject (required), user_approved (required), +1 more.
set_message_flag_statusA
Flag or unflag a message. Only call after the user explicitly approved this exact action.
Inputs: account (required), is_flagged (required), message_id (required), user_approved (required), +1 more.
set_message_read_statusA
Mark a message read or unread. Only call after the user explicitly approved this exact action.
Inputs: account (required), is_read (required), message_id (required), user_approved (required), +1 more.
set_work_modeA
Set the local AI-mail work mode. The mode controls whether this MCP may queue, draft, or send. This does not change Apple Mail.
Inputs: mode (required), user_approved (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools target clearly distinct resources, and descriptions add explicit ordering hints (e.g. 'use after list_messages'). However, the send path is crowded—create_draft, create_reply_draft, queue_email_for_approval, approve_queued_email, preview_send, and send_email all overlap enough that an agent could pick the wrong one without careful reading.
Every tool follows a clean verb_noun snake_case pattern (list_messages, create_draft, set_message_read_status, get_audit_log, queue_email_for_approval). No mixing of conventions or vague single-word verbs.
At 26 tools this sits at the heavy end, spanning mail actions, an approval queue, contact context, audit, and work modes. Each tool is scoped, but the count is large for a single mail server and risks cognitive overhead.
Strong lifecycle coverage: messages can be listed, searched, read, moved, flagged, and marked read; drafts/send/reply exist; the approval queue has full queue/list/approve/discard support; contacts and work modes are covered. Minor gaps remain (no message delete/archive, no mailbox creation or attachment handling).
Maintenance
Related MCP Connectors
Search and triage all your mailboxes; draft replies and campaigns; send only as you allow.
Read, search and draft email; nothing is sent until you confirm.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Stateful email for AI agents: read inboxes, reply in-thread, draft with approval.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables using Apple Mail accounts to search, read, manage, draft, and send messages from Codex or Claude Code locally.MIT
- AlicenseNot gradedqualityBmaintenanceEnables controlling Apple Mail on macOS through JavaScript for Automation, using already-configured accounts without passwords. Supports listing accounts and mailboxes, searching and reading messages, managing folders and message state, handling drafts and attachments, and moving, trashing, or sending mail.16 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, send, schedule, manage, and analyze mail across multiple IMAP/SMTP accounts, including drafts, provider-aware labels, real-time IDLE triage, verification-code capture, and calendar extraction. Runs over stdio for local clients or Streamable HTTP for networked access, with a guided setup wizard and OAuth2 support.-
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to read, search, send, schedule, and organize mail across multiple IMAP/SMTP accounts, including drafts, provider-aware labels, analytics, calendar extraction, and real-time inbox watching with verification-code capture. Runs over stdio or Streamable HTTP and supports auto-detected providers, OAuth2, and multi-account operation.31 npmISC