apple-mail-mcp

<p align="center">
  <img src="icon.png" width="96" alt="">
</p>

<h1 align="center">Apple Mail, Calendar & Notes MCP</h1>

<p align="center">
  Let your AI assistant read, search, triage and send your mail, manage your calendar and keep notes —<br>
  using the Mail, Calendar and Notes apps already on your Mac. Works with any MCP client.
</p>

<p align="center">
  <a href="../../releases/latest"><b>Download the latest release</b></a> ·
  <a href="#install">Install</a> ·
  <a href="#what-it-can-do">What it can do</a> ·
  <a href="#faq">FAQ</a>
</p>

---

## Why this exists

Most AI mail connectors live in the cloud and only work with Gmail or Outlook. If your mail lives in **Apple Mail** — a self-hosted IMAP server, iCloud, a company account — there was no clean way to give an assistant access.

This [MCP](https://modelcontextprotocol.io) server talks to the apps on your Mac directly. That means:

- **Any MCP client.** Desktop chat apps, local-model apps, coding agents — anything that can start an MCP server over stdio.
- **Any account Apple Mail can open works.** Self-hosted, iCloud, Exchange, Gmail-via-IMAP — if it's in Mail.app, your assistant can see it.
- **Nothing to install.** No Node, no Python, no Homebrew. It runs on JavaScript for Automation, which ships with every Mac.
- **Your mail stays on your Mac.** The server has no network code. The assistant only sees what it asks for; where that goes next depends on your model (a local model keeps everything on the Mac).
- **Two permission prompts, not thirty.** Everything is grouped into a `read` tool and a `write` tool. Approve `read` once and forget about it.
- **Works with small local models too.** Arguments are forgiving (`"true"`, `"3 days ago"`, `folder` instead of `mailbox`), and every mistake comes back with a plain "how to fix" line instead of a dead end.

## What it can do

Ask in plain words — *"what's waiting for my reply?"*, *"forward the printer invoice to accounting"*, *"put a call with Sam on Tuesday at 1pm"*, *"save the PDFs from the contract email"*. Under the hood:

### 📥 Triage — *"what needs my attention?"*

| | |
| --- | --- |
| **Needs response** | Emails from real people you haven't answered yet. Ignores no-reply senders and notifications. |
| **Awaiting reply** | Emails *you* sent that none of the recipients has answered. Great for follow-ups. |
| **Conversation view** | A whole thread in order — their messages and your replies — from every folder, including Sent. Messages count as one conversation only when the subject *and* the people match. |
| **Replied / forwarded / flagged** | Every message in a list shows whether you already replied, so the assistant doesn't nag you twice. |

### 🔎 Read & search

| | |
| --- | --- |
| **Inbox and folders** | Latest messages in any folder, unread counts, all accounts. |
| **Search** | By subject, sender or message text; by date range; unread, flagged or with attachments; in one folder or everywhere. |
| **Read a message** | Headers, recipients, plain-text body (long ones in pages) and a list of attachments. |
| **Attachments** | See names, sizes and types — and save them into your attachments folder. |

### ✉️ Write

| | |
| --- | --- |
| **Send** | New emails with To / Cc / Bcc, from any of your addresses, with files attached. |
| **Reply / reply all** | With the original quoted below. Opens as a draft you check and send. |
| **Forward** | With attachments and an optional note on top. Opens as a draft too. |
| **Draft mode** | Replies and forwards open in Mail by default, because Mail itself picks their recipients and quote. New emails can open as drafts as well. |

### 🗂 Organize

| | |
| --- | --- |
| **Folders** | Create folders, including nested ones (`Alerts/Kubernetes`). |
| **Move & delete** | Move messages between folders or to the account's Trash — with a **dry run** that shows what would change first. |
| **Flags & read status** | Flag in any colour, mark read or unread — one message or a batch. |
| **Rules** | Create, list, enable, disable and delete Mail rules, so new mail sorts itself. |

### 📅 Calendar

| | |
| --- | --- |
| **Events** | See what's on for any date range across all calendars, repeating events included; create and delete events. A date alone makes an all-day event. |

### 📝 Notes

| | |
| --- | --- |
| **Browse & search** | Folders, recent notes, search by title or text. Recently Deleted stays hidden unless you ask. |
| **Write** | Create notes, append to them or rewrite them; delete to Recently Deleted. |

## Install

You need macOS 14 or later (older versions will likely work but aren't tested) and an MCP client.

### Any MCP client

Get the code — `git clone https://github.com/ipsupport-llc/apple-mail-mcp`, or unzip the `.mcpb` from the [latest release](../../releases/latest) — and add the server to your client's config. It runs on the Mac's own `osascript`:

```json
{
  "mcpServers": {
    "apple-mail": {
      "command": "/usr/bin/osascript",
      "args": ["-l", "JavaScript", "/path/to/apple-mail-mcp/server/apple-mail-mcp.js"]
    }
  }
}
```

`./install.sh --print` prints this block with the right path. The server is also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.ipsupport-llc/apple-mail-mcp`.

The first time the assistant touches Mail, Calendar or Notes, macOS asks whether your client may control them — click **Allow**.

### Claude Desktop (one click)

1. Download **`apple-mail-mcp.mcpb`** from the [latest release](../../releases/latest).
2. Double-click it and click **Install**.

Updates, settings and removal live in **Settings → Extensions**.

### Settings

As environment variables in the server's `env` (Claude Desktop: **Settings → Extensions → Apple Mail, Calendar & Notes → Configure**):

| Variable | What it does |
| --- | --- |
| `APPLE_MAIL_READ_ONLY=true` | Removes the `write` tool entirely. The assistant can read and search, but can't send, move, delete or create anything. A good default for a shared or work machine. |
| `APPLE_MAIL_DEFAULT_ACCOUNT` | Used when the assistant doesn't name an account, e.g. `Work`. |
| `APPLE_MAIL_SAVE_DIR` | Where saved attachments go. Defaults to `~/Downloads`; `~` and `${HOME}` are expanded. |
| `APPLE_MAIL_TIMEOUT` | Seconds one call may take before it is stopped (default 25). |

### Tool permissions

Most clients ask before using a tool. We recommend allowing `read` once and approving `write` each time, so you always see what gets sent, moved or deleted.

## Safety

- **Mail and notes are never deleted for good.** Mail goes to the account's Trash, notes go to Recently Deleted. Where that isn't possible — an account without a Trash folder, a Notes account without Recently Deleted (e.g. Exchange), something already in the trash, a locked note — the extension refuses and says why. Mail rules that delete are only allowed when every account keeps deleted mail in its Trash.
- **Calendar events and rules have no trash in macOS.** Deleting one returns a full copy of it, so it can be recreated on request.
- **Replies and forwards are drafts by default.** You see the real thing in Mail and press *Send* yourself. `dry_run: true` shows exactly what would go out — recipients (Reply-To and reply-all included), subject and the full text — and a reply is not sent if Mail would address it differently. Results of a send list what Mail actually sent.
- **Nothing hangs.** Mail, Calendar and Notes are driven from a separate worker process: a call that takes longer than the timeout is stopped with a clear error, `ping` and `tools/list` always answer, and a cancelled call really stops. A write that timed out is not repeated blindly. Each call is logged to stderr with its app and duration.
- **Permissions explained.** A missing Automation permission, an app that is not running or a lost connection comes back as a plain "how to fix" instead of an error code.
- **No accidental repeats.** The same send, reply, delete or create call twice within 15 minutes is refused — a stuck model can't send an email five times.
- **Repeating events are deleted only on purpose.** Deleting one removes the whole series, so the extension asks for `whole_series: true`.
- **Dry runs.** Bulk moves and deletes can be previewed before they happen.
- **Attachments stay in one place.** They are saved only inside the attachments folder from the settings and are never overwritten — an existing file gets `(1)`, `(2)`… appended. Files attached to outgoing mail also come only from that folder, so "attach ~/.ssh/id_rsa" is refused; files from other tools (say, a Seafile download) go there first.
- **Attachments are checked.** If Mail does not take every file, the message is not sent: it opens as a draft instead.
- **Watch out for instructions hidden in emails.** Anything the assistant reads becomes part of its context, and a malicious email could try to tell it to do something. Keep `write` on manual approval, or turn on read-only mode, if that worries you.
- **One readable file.** The whole server is [`server/apple-mail-mcp.js`](server/apple-mail-mcp.js), with no dependencies and no network calls.

## FAQ

**Do Mail rules run when my Mac is asleep?**
No. Apple Mail rules only run while Mail is open, and only on new mail. To sort old mail, ask the assistant to move it. If your mail server supports Sieve, server-side filters are more reliable across devices.

**The assistant can't read a note.**
It's probably locked. Unlock it in Notes first; locked notes stay private.

**Search is slow.**
Apple Mail's scripting is slow on very large folders, and searching message text is the slowest. Narrow it to an account, a folder or a date range.

**The tools don't show up.**
Check that the server is enabled in your client, then restart the client. `./test.sh` talks to the server directly, without any client. (Claude Desktop: **Settings → Extensions**; logs in `~/Library/Logs/Claude/`.)

**"Not authorized to send Apple events".**
Open