Skip to content
Agentmart
Submit a tool

Apple Mail

Search, read and act on Apple Mail — threads, attachments, body search, writes off by default

Connector by mgcrea · GitHub account verified by the MCP Registry

IndexedMITLocal (stdio)★ 5
Write a review

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/mgcrea-mcp-apple-mail

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

Search, read and act on Apple Mail — threads, attachments, body search, writes off by default

Use cases: email

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools
13 read · 6 write · 5 delete · 1 not yet classified
Secrets
None asked for
Install scripts
None found
Runs as
Node.js package

Tools by what they do 25

Read from the source code; the running server may list different tools.

Read 13 · Look things up without changing anything.

  • apple_mail_count_messages
  • apple_mail_diagnostics
  • apple_mail_find_thread
  • apple_mail_get_message
  • apple_mail_get_message_source
  • apple_mail_get_thread
  • apple_mail_list_accounts
  • apple_mail_list_attachments
  • apple_mail_list_mailboxes
  • apple_mail_list_messages
  • apple_mail_list_open_drafts
  • apple_mail_query
Show 1 more tools
  • apple_mail_search_messages

Write 6 · Create, change, send or run things.

  • apple_mail_check_for_new_mail
  • apple_mail_create_mailbox
  • apple_mail_draft_reply
  • apple_mail_move_messages
  • apple_mail_save_attachment
  • apple_mail_set_message_flags

Delete 5 · Delete, drop, revoke or wipe things.

  • apple_mail_delete_messages
  • apple_mail_forward_message
  • apple_mail_reply_to_message
  • apple_mail_send_message
  • apple_mail_update_draft

Not yet classified 1 · We could not tell from the name and description.

  • apple_mail_triage

Secrets and settings it asks for

Other settings (environment variables or headers).

  • APPLE_MAIL_ACCOUNTS
  • APPLE_MAIL_ALLOW_FILE_SEND
  • APPLE_MAIL_ALLOW_WRITES

Network hosts it talks to 2

  • cupertino.mgcrea.io · found in code
  • github.com · found in code

Files it touches

  • Your home directory (~)
  • Any path the agent passes to its tools

Tools (25)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

  • apple_mail_check_for_new_mail

    Ask Mail to sync now, for one account or all of them. Unlike the read tools this will launch Mail if it is not running, and it causes real network activity against the mail servers, which is why it is a write-gated tool.

  • apple_mail_count_messagesread-only

    Count messages in a mailbox. Cheap in both lanes, so this works with no extra permissions. The `unread` figure is reported per source: Mail's own cached count is fast but can be flatly wrong (observed reporting 0 for a mailbox holding 1618 unread messages), so treat the index figure as authoritative when it is present.

  • apple_mail_create_mailbox

    Create a mailbox (a folder). Use this before apple_mail_move_messages when the destination does not exist yet — a move to a mailbox that is not there fails, and this is the only way to make one from here. Nest with "/": "Projects/Cupertino" creates Cupertino inside Projects. Omit `account` to create a local mailbox under On My Mac. ON A SERVER ACCOUNT (iCloud, Gmail, Exchange, any IMAP) THIS CREATES THE FOLDER ON THE SERVER: it syncs to the user's phone and every other device within seconds, and there is no delete tool here to undo it. Calling it for a name that already exists is safe and does…

  • apple_mail_delete_messagescan change or delete data

    Delete messages. This follows the account's own 'move deleted messages to Trash' setting, which this server does not control — for an account with that setting off, deletion is immediate and NOT recoverable from here. The response reports which behaviour applied. Requires confirm: true.

  • apple_mail_diagnosticsread-only

    Report what this server can currently do and why. Shows whether Mail is running, whether Automation and Full Disk Access are granted, where Mail's data lives, whether the search index is readable and how stale it is, whether the message file lane actually resolves and reads a real message per account, per-account message caching, and the active write/allowlist settings. Call this first whenever a tool returns `degraded: true` or a permission error — it names the exact System Settings pane to open.

  • apple_mail_draft_replyDraft a reply

    Read a thread properly, then leave a written draft in Mail for review. Never sends: the draft waits for a human. Requires writes to be enabled.

  • apple_mail_find_threadFind a thread about something

    Track down a conversation from a vague description — a project name, a person, something half-remembered — spending the cheap search lanes before the expensive body lane.

  • apple_mail_forward_messagecan change or delete data

    Forward a message to new recipients. By default it opens a draft in Mail for review. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. When a note is given, success means it was read back out of the composer window and matched. Filling the composer brings Mail to the front for a moment and borrows the clipboard, both of which are put back.

  • apple_mail_get_messageread-only

    Read one message: decoded headers, the plain-text body, and a list of its attachments. HTML-only mail is converted to text. Long bodies are truncated with an explicit marker rather than silently cut. Reads the message file directly when Full Disk Access allows, and otherwise asks Mail, which is slower but works — so this tool does not need the search index.

  • apple_mail_get_message_sourceread-only

    Get the raw RFC 5322 source of a message — every header and the undecoded body. Use this for header forensics (Received chains, SPF/DKIM/DMARC results, List-Unsubscribe), not for reading mail: apple_mail_get_message gives you the readable version without the noise. Capped and pageable via offset.

  • apple_mail_get_threadread-only

    Get every message in the conversation containing a given message, oldest first, across mailboxes and accounts. Metadata only — use apple_mail_get_message for bodies. Requires Full Disk Access.

  • apple_mail_list_accountsread-only

    List the mail accounts configured in Apple Mail: display name, UUID, type, addresses and mailbox names. Start here — the account name or UUID is what every other tool takes, and the mailbox names come back exactly as Mail spells them.

  • apple_mail_list_attachmentsread-only

    List a message's attachments: filename, MIME type, size and whether the bytes are present locally. Metadata only — it never returns file contents. A size of 0 with a filename means Mail stored the attachment outside the message file, which is normal.

  • apple_mail_list_mailboxesread-only

    List mailboxes, optionally with message counts. Counts cost one round-trip per mailbox (~0.3s each), so `withCounts` is off by default — turn it on for one account, not for all of them. Note that `unread` here is Mail's cached badge value and can be wrong; apple_mail_count_messages reports both sources.

  • apple_mail_list_messagesread-only

    List the newest messages in one mailbox, most recent first. Returns a `ref` per message that the read and action tools take. Without the search index this runs over Apple Events and is capped (default 50) because each additional message costs about 40ms per field — ask for 20 unless you have a reason not to. For anything involving a filter, use apple_mail_search_messages.

Show 10 more tools
  • apple_mail_list_open_draftsread-only

    Read the drafts the user has open in Mail right now — every compose window, with its subject, From, the recipients' names as shown, the text they wrote separated from the quoted message below it, and the opening of that quote. Reach for this when the user says 'review my draft', 'check this email before I send it' or 'what do you think of my reply' without naming a message: the draft in front of them may never have been saved where a search finds it, and the window is the current text either way. `main: true` marks the window in front. Each draft carries `savedDrafts`, the refs Mail autosaved …

  • apple_mail_move_messages

    Move messages to another mailbox, optionally in another account. The refs you passed in are DEAD afterwards: a moved message gets a new row id, so the response returns fresh refs and reports any message it could not re-locate. Requires confirm: true.

  • apple_mail_queryread-only

    Answer a question ABOUT your mail without reading the mail. Takes the same index filters as apple_mail_search_messages, plus two things it cannot do: `select` to keep only the fields you need, and `groupBy` to get counts per sender, mailbox, subject, day or month. Reach for this whenever the question is 'how many', 'who most', 'which mailbox' or 'when' — one grouped call replaces paging through hundreds of messages and tallying them by hand. Grouping counts every match, not just the first `limit`. Body search is not offered here (it is a linear file scan, which does not belong behind an aggreg…

  • apple_mail_reply_to_messagecan change or delete data

    Reply to a message. By default it opens a draft in Mail with the original quoted beneath your text, for the user to review. Pass replyToAll to include every original recipient. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. Success means the body was read back out of the composer window and matched, and only then may it be described to the user as ready. A failure is NOT automatically an empty draft: read the note, which says what was actually found — including that the composer was taken by someone using the Mac, in which case the reply may already have been S…

  • apple_mail_save_attachment

    Save one attachment to disk. It can only write into APPLE_MAIL_ATTACHMENT_DIR (default ~/Downloads) and will not overwrite an existing file unless you ask it to. Write-gated because it puts a file on the user's disk, even though it changes nothing in Mail.

  • apple_mail_search_messagesread-only

    Search mail by any combination of text, body text, sender, recipient, subject, mailbox, account, read/flagged state, attachments and date range. This is the tool to reach for whenever a filter is involved — it reads Mail's own search index, so it is fast even across a six-figure archive. Returns a `ref` per message for the read and action tools. Requires Full Disk Access; without it this returns degraded:true and you should fall back to apple_mail_list_messages on a specific mailbox.

  • apple_mail_send_messagecan change or delete data

    Compose a new message. By DEFAULT this does not send: it opens a draft in Mail for the user to review, which is almost always what you want. Only pass sendNow: true (with confirm: true) when the user has explicitly asked for the mail to go out now.

  • apple_mail_set_message_flags

    Set read / flagged / junk state on one or more messages. Pass only the fields you want to change; the rest are left alone. This is one tool rather than four because the four are one Apple Event when batched, and because refs in the same mailbox are grouped into a single round-trip. The response reports the state Mail re-read after the change, not what was requested — Mail's search index updates on its own schedule, so a follow-up search may briefly still show the old value.

  • apple_mail_triageTriage a mailbox

    Work through what arrived and report what needs a human: who is waiting, what is committed to, what can be ignored. Read-only — it proposes, it does not file or reply.

  • apple_mail_update_draftcan change or delete data

    Replace the body of an unsent draft, add files to it, or both — including a REPLY draft you have just written and been asked to revise or attach something to, which is the usual reason to reach for this. For a draft the user has open, apple_mail_list_open_drafts gives its ref under `savedDrafts`. It takes one of two routes and the result says which in `method`. `inPlace`: the draft's own composer window is still open in Mail, so the body is edited in that window and files are pasted in after the text, above any quoted original; each file must read back in the window before anything is saved. N…

Signals

Stars
5
Forks
0
Open issues
2
Weekly downloads
400
Last commit (this folder)
Oct 22, 2026 (7 days ago)
Last release
Oct 25, 2026 (4 days ago)
Last package publish
Oct 22, 2026 (7 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name
io.github.mgcrea/mcp-apple-mail
Version
1.31.0
Auth
No auth
Packages
npm @mgcrea/mcp-apple-mail
License
MIT
Repository
github.com/mgcrea/cupertino
Website
cupertino.mgcrea.io
First seen
Oct 24, 2026
Last checked
Oct 26, 2026
Source
Official MCP Registrygithub-graphql

More from mgcrea

Cite this page

Apple Mail MCP server. Agent Mart. https://agentmart.dev/connectors/mgcrea-mcp-apple-mail (last updated 2026-10-26)