applemail-mcp-server

A local MCP server that gives Claude access to macOS Mail.app through JXA (JavaScript for Automation). Every account already configured in Mail — iCloud, Gmail, Outlook/Exchange, IMAP — becomes visible, with no OAuth, no API keys, and no data leaving the machine.

Read-only by default. There is no send tool, by design.

Tools

Tool	Writes?	What it does
apple_mail_list_accounts	no	Account names, types, addresses. Start here.
apple_mail_list_mailboxes	no	Mailboxes + unread counts (names are case-sensitive and localised).
apple_mail_unread_summary	no	Unread counts per account/mailbox. Reads counters only — fast on huge mailboxes.
apple_mail_search_messages	no	Header search with filters; returns opaque per-message handles.
apple_mail_get_message	no	Full headers, recipients, attachment names and body for one handle.
apple_mail_set_message_status	yes	Mark read/unread/flagged. Disabled unless you opt in.
apple_mail_compose_draft	yes	Opens a pre-filled compose window. Never sends — you click Send.
apple_calendar_list_calendars	no	Calendar names + writable flag. Call before creating an event.
apple_calendar_create_event	yes	Create one event in Apple Calendar only. Disabled unless you opt in. Skips duplicates.

Requirements

• macOS with Mail.app configured (at least one account)
• Node.js 18+

Build

npm install
npm run build
node dist/index.js --doctor   # verifies Mail.app is reachable and permissions are granted

Configure Claude Desktop and/or Claude Code

Both hosts need an absolute path to node and to dist/index.js — Claude Desktop launches the server with a stripped environment, so a bare node on PATH will not resolve.

npm run configure

This detects the exact node binary running the script (process.execPath — correct regardless of nvm/fnm/volta/homebrew, and survives a node version switch by just re-running the command), writes/updates the apple-mail entry in claude_desktop_config.json, and re-registers it with claude mcp add for Claude Code. Flags:

Flag	Effect
--calendar-writes	sets APPLE_MAIL_MCP_ALLOW_CALENDAR_WRITES=1 on the registered entry
--status-writes	sets APPLE_MAIL_MCP_ALLOW_STATUS_WRITES=1
--skip-desktop	only touch Claude Code
--skip-code	only touch Claude Desktop

Run once per target if you want different write policy on each (e.g. npm run configure -- --calendar-writes --skip-code then npm run configure -- --skip-desktop).

After running it, quit Claude Desktop with Cmd+Q — closing the window is not enough, the config is only read at startup — and reopen it. If the server does not appear, check ~/Library/Logs/Claude/mcp*.log.

Manual alternative, if you'd rather not run the script — edit ~/Library/Application Support/Claude/claude_desktop_config.json directly:

{
  "mcpServers": {
    "apple-mail": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/applemail-mcp-server/dist/index.js"]
    }
  }
}

and register Claude Code with:

claude mcp add --transport stdio --scope user apple-mail -- node /ABSOLUTE/PATH/TO/dist/index.js

macOS permissions

The first call triggers a system prompt to let the host app control Mail. If you dismissed it, go to System Settings → Privacy & Security → Automation and enable Mail under Claude (or Claude Code / Terminal, whichever launched the server). Re-launch the host app afterwards.

Environment variables

Variable	Default	Effect
APPLE_MAIL_MCP_ALLOW_STATUS_WRITES	off	Set to 1 to register the read/flag tool.
APPLE_MAIL_MCP_ALLOW_COMPOSE	on	Set to 0 to remove the compose-window tool.
APPLE_MAIL_MCP_ALLOW_CALENDAR_WRITES	off	Set to 1 to register apple_calendar_create_event.
APPLE_MAIL_MCP_TIMEOUT_MS	90000	Per-operation timeout.

For the strictest posture, leave status and calendar writes off and set APPLE_MAIL_MCP_ALLOW_COMPOSE=0. The server is then incapable of modifying anything.

Design notes

Apple Events are the bottleneck. Each property access is an IPC round-trip, so the server never loops over messages individually — it uses bulk getters (spec.subject() returns the whole column in one event) and pushes filters down into Mail.app via whose. since_days defaults to 30 and search_messages refuses rather than hangs when more than max_scan (default 400) messages match, returning an error that tells the agent how to narrow the query.

Handles, not IDs. Search returns an opaque base64 handle encoding account + mailbox + Mail's internal row id, so a follow-up read is a direct lookup rather than a re-scan. Handles go stale if the message is moved or deleted; the error says so and tells you to search again.

No string interpolation into script source. Parameters are passed to osascript as a single JSON argv entry and parsed inside the script, so mailbox names and search terms cannot inject code.

Body search is not supported. query matches subject and sender only — searching bodies over Apple Events on a large mailbox is pathologically slow. Use Mail's own search for that.

Calendar writes go to Apple Calendar only. apple_calendar_create_event never touches Google Calendar, Outlook, or any other service — it calls Calendar.app the same way compose_draft calls Mail.app. It skips (rather than duplicates) an event when one with the same title already exists on the same day in the same calendar, so a daily scan can be re-run safely. Date/time extraction from message text is left to the calling agent, not done with regex inside this server — Apple Events give no reliable way to validate a guessed date, so a wrong guess would silently create a bad event.

Daily mail-to-calendar automation

This server never runs on its own — an agent decides when to scan mail and whether a message describes something calendar-worthy, then calls apple_calendar_create_event. To get a daily scan, schedule a Claude Code routine (see the schedule skill) that runs once a day with a prompt along these lines:

Call apple_mail_search_messages (since_days: 1) across all accounts, read anything that looks
like a meeting, appointment, or deadline with apple_mail_get_message, then call
apple_calendar_list_calendars and apple_calendar_create_event to add each one to the right Apple
Calendar. Never invent a date. Report what was created and what was skipped.

Requires APPLE_MAIL_MCP_ALLOW_CALENDAR_WRITES=1, and Mail.app / Calendar.app must both be reachable when the routine fires (the host machine needs to be on and unlocked).

Security

This server reads your entire mailbox. Two things worth keeping in mind:

1. Email bodies are untrusted input. A message can contain text aimed at the model rather than at you. The get_message description tells the model to treat message contents as data and never as instructions, but a read-only configuration is what actually bounds the blast radius — keep the write tools off unless you need them.
2. Scope matters more than trust. If the mailbox holds client, government or UN correspondence, consider pointing searches at a specific account or archive mailbox rather than letting the server roam every account.

Limitations (v0.1)

• No send, move, delete, or attachment extraction
• No true threading — search by subject or sender to group a conversation
• Plain-text bodies only (Mail returns the text part; HTML markup is not preserved)
• macOS only

License

MIT