Apple Mail, Calendar & Notes

io.github.ipsupport-llcPublished by GitHub account ipsupport-llcv1.6.1Updated Oct 25, 2026

Apple Mail, Calendar and Notes on macOS for any MCP client. Local, no dependencies.

VerifiedSTDIODesktop onlyProductivity & WorkflowCommunication & Collaboration

Overview

AI-generated overview

A local macOS MCP server that lets an assistant read, search, triage and send Apple Mail, manage Calendar events and edit Notes through the built-in apps.

What you can do
Triage and read mail: find messages needing a reply, awaiting a reply, view threads, list folders and unread counts, search by text, sender or date, read messages and list attachments across all Mail accounts. Write mail: send new emails with Cc/Bcc and attachments, reply, reply all and forward, opening as drafts by default. Organize mail: create folders, move and delete messages with dry runs, set flags and read status, and create, enable or delete Mail rules. Manage calendar: list events over a date range including repeating events, create and delete events. Work with notes: browse folders, list and search notes, read, create, append, rewrite and delete notes.
When to use it
Useful when your mail, calendar and notes live in the macOS Mail, Calendar and Notes apps, including self-hosted IMAP, iCloud or Exchange accounts, and you want a local assistant to triage, draft replies, schedule events or keep notes without a cloud connector.
Requirements
macOS 14 or later (older versions untested) and an MCP client that can start a local stdio server. Runs on the Mac's built-in osascript with no Node, Python or other dependencies. The client must be granted Automation permission to control Mail, Calendar and Notes. Optional environment variables: APPLE_MAIL_DEFAULT_ACCOUNT, APPLE_MAIL_READ_ONLY, APPLE_MAIL_SAVE_DIR.
Before you install
The write tool can send email, move and delete messages, create and delete calendar events and rules, and change notes; keep it on manual approval or set APPLE_MAIL_READ_ONLY=true. Deletions go to Trash or Recently Deleted where available, but calendar events and rules have no trash and are only returned as a copy. Content read from emails can carry injected instructions. Attachments are saved only inside the configured folder, and outgoing attachments must come from it. Mail rules only run when

Installation

In SourceWeft

  1. Open Apple Mail, Calendar & Notes in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Image]

Apple Mail, Calendar & Notes MCP

Let your AI assistant read, search, triage and send your mail, manage your calendar and keep notes —
using the Mail, Calendar and Notes apps already on your Mac. Works with any MCP client.

Download the latest release · Install · What it can do · FAQ

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 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 responseEmails from real people you haven't answered yet. Ignores no-reply senders and notifications.
Awaiting replyEmails you sent that none of the recipients has answered. Great for follow-ups.
Conversation viewA 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 / flaggedEvery message in a list shows whether you already replied, so the assistant doesn't nag you twice.

🔎 Read & search

Inbox and foldersLatest messages in any folder, unread counts, all accounts.
SearchBy subject, sender or message text; by date range; unread, flagged or with attachments; in one folder or everywhere.
Read a messageHeaders, recipients, plain-text body (long ones in pages) and a list of attachments.
AttachmentsSee names, sizes and types — and save them into your attachments folder.

✉️ Write

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

🗂 Organize

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

📅 Calendar

EventsSee 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 & searchFolders, recent notes, search by title or text. Recently Deleted stays hidden unless you ask.
WriteCreate 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 — 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 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.
  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):

VariableWhat it does
APPLE_MAIL_READ_ONLY=trueRemoves 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_ACCOUNTUsed when the assistant doesn't name an account, e.g. Work.
APPLE_MAIL_SAVE_DIRWhere saved attachments go. Defaults to ~/Downloads; ~ and ${HOME} are expanded.
APPLE_MAIL_TIMEOUTSeconds 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, 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 System Settings → Privacy & Security → Automation and allow your MCP client (the app that starts the server) to control Mail, Calendar and Notes.

Tool reference (for the curious)

Two tools, each taking { "action": "...", "args": { ... } }. The full list of arguments is in each tool's description.

read — never changes anything

ActionPurpose
needs_responseEmails from people that wait for your answer
awaiting_replyYour sent emails with no answer
get_threadWhole conversation, oldest first
list_messagesLatest messages in a folder, with replied / forwarded / flagged
search_messagesText (subject, sender, body), dates, unread, flagged, attachments, all folders
read_messageOne full message
list_attachmentsAttachments of a message
list_accountsMail accounts and addresses
list_mailboxesFolders with unread counts
list_rulesMail rules with conditions and actions
list_calendarsCalendars
list_eventsEvents in a date range, repeating events expanded
list_note_foldersNotes accounts and folders
list_notesRecent notes
search_notesSearch notes
read_noteOne full note

write — changes things (hidden in read-only mode)

ActionPurpose
send_emailNew email, attachments from the attachments folder (draft: true opens it instead)
reply_messageReply / reply all — opens as a draft in Mail by default, draft: false sends
forward_messageForward with attachments — draft by default, draft: false sends
set_readMark read / unread, one or many
set_flagFlag / unflag with colour
move_messagesMove to another folder (dry_run available)
delete_messagesMove to the account's Trash (dry_run available)
save_attachmentsSave attachments into the attachments folder
create_mailboxNew folder
create_rule · set_rule_enabled · delete_ruleMail rules (a deleted rule comes back as a copy)
create_event · delete_eventCalendar events (whole_series: true to delete a repeating one; a deleted event comes back as a copy)
create_note · update_note · delete_noteNotes

Message ids come from list and search results; pass account and mailbox from the same row. If the folder is wrong, the message is found by its id anyway.

Small models get help: argument names are matched loosely (folder → mailbox, messageId → id), values are converted ("false", "1,2,3", "tomorrow"), short action names work (reply, search), and every result explains in notes how the call was read. Anything that sends, deletes or creates is never guessed: there, unclear input is an error with a hint.

Manual install & development

Run the server straight from a checkout instead of the .mcpb:

sh
git clone https://github.com/ipsupport-llc/apple-mail-mcp.git ~/code/apple-mail-mcpcd ~/code/apple-mail-mcp./install.sh --print   # any client: prints the config block to paste./install.sh     # Claude Desktop: adds an "apple-mail" entry to claude_desktop_config.json (backs it up first)./test.sh        # talks to the server directly and prints your accounts and calendars./uninstall.sh   # removes the entry

install.sh takes the same settings as the extension: --read-only / --no-read-only, --account Work, --save-dir ~/Documents/Attachments. Running it again keeps earlier settings unless you change them (--reset forgets them).

Restart Claude Desktop after install.sh. Don't use the manual install and the .mcpb at the same time.

Tests never touch your mail: unit tests run the server against fake Mail, Calendar and Notes apps, protocol tests only speak JSON-RPC. CI runs both on macOS for every pull request.

sh
/usr/bin/osascript -l JavaScript tests/unit.js server/apple-mail-mcp.jspython3 tests/protocol.py

Releasing: push a tag and GitHub Actions runs the tests, builds the .mcpb, attaches it to a release and lists it in the MCP Registry.

sh
git tag v1.4.0 && git push origin v1.4.0

License

MIT © IPSupport LLC. Some feature ideas were inspired by patrickfreyer/apple-mail-mcp (MIT).

Source: README.md at commit 44185fe

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

3
  1. v1.6.1LatestOct 17, 2026
  2. v1.5.1Oct 16, 2026
  3. v1.4.0Oct 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts