macOS Apps

io.github.elfenskyPublished by GitHub account elfenskyv0.15.1Updated Oct 26, 2026

Mail, Calendar, Reminders, Notes, Messages and more on macOS: cited pointers, previewed deletes

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

Local macOS-only MCP server that lets an assistant read and write Mail, Calendar, Reminders, Notes, Messages, Contacts, Photos, Safari and Shortcuts.

What you can do
  • Search and list Mail, Notes, Messages, Contacts, Photos, Safari tabs and Shortcuts as pointers, then fetch bodies on request
  • Read calendars, free/busy gaps, reminders, mail overviews, threads, attachments and mail needing a reply
  • Create and update events, reminders, notes, drafts and contacts, with recurrence rules
  • Preview and then move, trash, delete or undo mail, notes, events and reminders, with backups and an audit log
  • Open Safari pages, run Shortcuts, export photos, and check permissions or usage with doctor and audit tools
When to use it
Useful when you want an assistant on a Mac to answer questions about your calendar, inbox, notes or messages and to carry out careful, previewed changes in those apps. Best for people who want one local server covering many Apple apps instead of several separate ones.
Requirements
macOS only, with Python 3.12 or newer and uv (uvx) to run the PyPI package locally over stdio. macOS privacy grants are needed: EventKit for Calendar and Reminders, Automation per app for Mail, Notes, Contacts, Safari, Messages and Music, and optionally Accessibility and Full Disk Access for richer reads and replies. No API keys or environment variables are required.
Before you install
It reads private local data such as mail, messages, notes, photos and contacts, and reads may open apps or local stores. Writes change real data; deletes, moves and sends preview by default but other writes act immediately, and mail moves and trashes are backed up locally. Send tools are off unless enabled through the allow-send command or MACOS_APPS_ALLOW_SEND, and a sent result means Mail accepted the message, not that it was delivered. Safari opening and Shortcuts can reach the network…

Installation

In SourceWeft

  1. Open macOS Apps 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

macos-apps-mcp

[macos-apps-mcp logo]

[elfensky/macos-apps-mcp MCP server]

One local MCP server for Mail, Calendar, Reminders, Notes, Messages, Contacts, Photos, Safari, Music and Shortcuts on macOS. Searches and lists return pointers: an id, a one-line summary and a link that opens the item in its app. Bodies are a separate, capped fetch. Writes are tiered and audited; deletes, moves and sends preview first. macOS only. Python + FastMCP + uv. See DESIGN.md and CHANGELOG.md.

What you can ask

  • "What is on my calendar this week? When am I free on Thursday afternoon?"
    events, free_busy
  • "Which emails need a reply? Draft a reply to the first one."
    mail_needs_response, mail_reply. The reply opens as a draft in Mail. It is not sent.
  • "Move the newsletters in my inbox to Archive. Show me first."
    mail_search, move_mail, mail_undo. The move previews by default. mail_undo reverses it, within the known limits below.

Safety and privacy

  • Local. No telemetry, and no network requests of its own: only a local unix socket (shim to daemon) and the dashboard on 127.0.0.1. Three tools reach past the Mac through the apps, when called: the send tools (off by default) send through Mail, safari_open opens a page, and run_shortcut runs a Shortcut that can call the web.
  • Three tiers. Read, write and outbound. Send tools are absent until you enable them per app: macos-apps-mcp allow-send mail (daemon) or MACOS_APPS_ALLOW_SEND=mail (stdio). MACOS_APPS_READ_ONLY=1 registers reads only and wins over both.
  • Dry run first. dry_run defaults to true for delete_draft, move_mail, trash_mail, mail_undo, send_mail, reply_all, forward_mail, delete_reminder, delete_event, delete_note and update_note. Other writes act when called. mail_reply opens a draft only.
  • Audit log. Every write goes to ~/.local/state/macos-apps-mcp/audit.jsonl (under $XDG_STATE_HOME when set). An update or delete by id also records the item as it was. The audit tool reads the log back.
  • Mail recovery. Before a Mail move or delete, each message is copied as .eml under ~/.local/state/macos-apps-mcp/backup/mail/. mail_undo reverses the batch. No tool empties the Trash.
  • Known limits. A message Mail downloaded only in part is backed up without its attachments. Moves and trashes through a Gmail label folder are refused, because Gmail reverts them about 2 minutes later. sent: true means Mail accepted the message, not that it was delivered. All Mail facts.
  • Dashboard. Under the signed .app daemon, a local page (127.0.0.1 only) shows every write, what it changed, and the backup behind each Mail batch. Invented data below:

[The dashboard: three newsletters moved to Archive, each one backed up, and the prompt that undoes the batch]

First 5 minutes

Requires macOS, Python ≥ 3.12 and uv. uv provides uvx. The package is on PyPI. Point your MCP client at uvx. It fetches the package and runs it, so there is no clone and no venv path:

json
{  "mcpServers": {    "macos-apps": {      "command": "uvx",      "args": ["macos-apps-mcp"]    }  }}

If Claude Desktop cannot find uvx, set "command" to its full path: run which uvx in Terminal (a default uv install prints /Users/you/.local/bin/uvx).

For Claude Code:

sh
claude mcp add macos-apps --scope user -- uvx macos-apps-mcp

Or, instead of claude mcp add, install the Claude Code plugin. It starts the same server and adds a skill that teaches the dry-run workflow. In Claude Code, run /plugin marketplace add elfensky/macos-apps-mcp, then /plugin install macos-apps@macos-apps-mcp.

The CLI commands further down (allow-send, dedupe-mail) run the same way: uvx macos-apps-mcp allow-send.

Run doctor first. The doctor tool reports what is granted and opens no dialog (each Automation grant is read live; an app that is not running shows not_running). doctor(request=True), with you at the screen, opens the EventKit and Automation dialogs. The server needs:

  • EventKit: Calendar and Reminders.
  • Automation, one dialog per app: Mail, Notes, Contacts, Safari, Messages, Music.
  • Accessibility (optional, no dialog: turn it on in System Settings → Privacy & Security → Device Control and Data Access, called Accessibility before macOS 27, for the app that starts the server): mail_reply and reply_all put your text above Mail's own quote. Without it, those two refuse and create nothing. doctor and the Health page show whether it is on.
  • Full Disk Access (optional, no dialog: turn it on in System Settings → Privacy & Security → Full Disk Access, for the app that starts the server): Messages content, Photos, Mail's index reads, reminder tags and subtasks, and the fast Notes path. Without it, Notes and some Mail reads use a slower path. The rest return an error or a coverage note.

Under stdio, macOS gives each grant to the app that starts the server (Claude Desktop, Terminal, VS Code), so each client needs its own. The signed .app daemon holds one set for all: docs/DAEMON.md.

Load only the apps you use. MACOS_APPS_ADAPTERS_OFF=photos,music registers no tools for those apps, so your client holds fewer tools in its context. Under the daemon, see turn adapters off.

From source (development): use this path to work on the server itself.

sh
git clone https://github.com/elfensky/macos-apps-mcp && cd macos-apps-mcpuv sync

Then point your MCP client at the project's own venv python — deterministic, and it carries the locked PyObjC wheels:

json
{  "mcpServers": {    "macos-apps": {      "command": "/absolute/path/to/macos-apps-mcp/.venv/bin/python",      "args": ["-m", "macos_apps_mcp"]    }  }}

Why not apple-mcp?

apple-mcp by Dhravya Shah pioneered one MCP server for all Apple apps. It is now archived. It returned full note and email bodies inline. This server returns pointers, fetches bodies only on request, and gates every write by tier. See CREDITS.md.

Something broke? Run doctor and paste its output into a GitHub issue. The report shows process paths, so check them before you post.

Tools

Reads return pointers; results are capped per adapter. Bodies/content are a separate bounded fetch. Writes/actions are skipped entirely when MACOS_APPS_READ_ONLY is set (see below).

Calendar & Reminders — read/write (EventKit)

ToolArgsNotes
eventswhen = today | week | YYYY-MM-DDlist events as pointers
free_busystart, end (ISO), optional calendars idsmerged busy intervals + free gaps in the window; no event details
remindersdue = today | overdue | this-week | a list namelist reminders as {results, coverage?}; each result carries folder, tags and parent (read-only; needs EventKit and Full Disk Access)
calendars / reminder_lists—containers (id + name) to target writes
create_event / update_eventtitle, start, end (ISO), calendar, location, notes, all_day, recurrence, alarms (minutes before the start, at most 5; all-day: from local midnight, -540 = 09:00 on the day)update is a full replace by id, except alarms: omitted keeps the event's alarms, [] removes them
delete_eventid, span, dry_rundry_run previews without deleting; a real delete is verified gone (the occurrence, not the series)
create_reminder / update_remindertitle, due, list_name, notes, priority (0–9), start, recurrenceupdate is a full replace by id
create_reminder_listnamenew list on the default account; an exact duplicate name is refused
complete_reminderidmarks complete; completing a parent lists the subtasks it leaves open under subtasks; refused, changing nothing, when the Reminders store cannot be read (needs EventKit and Full Disk Access)
delete_reminderid, dry_run (default true), with_subtasksdeletes by id and proves it gone; a parent with subtasks is refused unless with_subtasks=true, since deleting it deletes them too (needs EventKit and Full Disk Access)

Event and reminder pointers carry folder = the calendar or list id, which free_busy(calendars=…) and the write tools (calendar=, list_name=) take.

Reminder tags and subtasks (tags, parent = the parent's id) are read from the Reminders store, read-only, and need Full Disk Access. When that store cannot be read, the reminders still come back and coverage says why. No public API writes a tag or nests a reminder, so no tool here does.

A write targets its container by name or Pointer.id; an ambiguous name raises rather than guessing. Recurrence is an RFC 5545 RRULE: FREQ, INTERVAL, COUNT, UNTIL, BYDAY (with ordinals such as 2TU or -1FR for monthly and yearly rules), BYMONTHDAY, BYMONTH, BYYEARDAY and BYSETPOS, e.g. FREQ=MONTHLY;BYDAY=2TU;COUNT=6. A recurring reminder needs a due date. BYWEEKNO, BYHOUR, BYMINUTE, BYSECOND and WKST are refused by name (EventKit saves BYWEEKNO but expands only the first date), and so is any value out of range or any combination RFC 5545 forbids; each part is checked again after the write. A start date that does not match its rule is accepted — RFC 5545 counts it as the first occurrence — and the event result says that the first occurrence is an extra one.

Mail — id-first read + draft-and-open (Automation)

Sending is off by default: reads, create_draft, and mail_reply never send — they open a compose window for you to review. Outbound (send_mail, reply_all, forward_mail) exists but only runs when the operator opts in via MACOS_APPS_ALLOW_SEND, and dry_run still defaults to True even then.

ToolArgsNotes
mailsubject-OR-sender substringinbox matches; id = stable RFC822 message-id, message:// deeplink
mail_bodyid, mailboxone message's plaintext, bounded + truncation-marked; mailbox is the folder value from a mail_search result passed back verbatim (or a canonical name) — any mailbox, not just the inbox
mail_searchsubject, from_, to, mailbox, account, since, until, unread, flagged, has_attachments, body, limitindexed search via Envelope Index (at rest — no Mail launch unless account= is a display name, which is resolved through Mail; a UUID stays pure sqlite, an unknown name raises); one result per message (INBOX preferred); has_attachments excludes inline images; body best-effort (indexed only)
mail_index_bodiesrebuildbuilds/refreshes opt-in FTS body index from .emlx at rest; resumable, size-capped; skips not-yet-downloaded (partial coverage by design)
mail_threadid, limit (default 100)whole conversation, oldest-first, includes your sent messages; deduped; over limit oldest dropped (thread read for reply)
mail_overview—every mailbox with total + unread, unread-first; includes Junk/Trash/All Mail; counts live (stored counters go stale) and per distinct message; account names come from Mail (launches it), UUIDs stand in when it's unreachable; On My Mac always named
mail_attachmentsmailbox (a search result's folder, verbatim — or inbox/sent/drafts/trash/junk), optional queryattachment name/size/downloaded per message; works on Drafts
mail_needs_response—inbox mail likely needing your reply, ranked with a reason (flagged / unread-direct / unanswered-direct); headers only, no bodies read
mail_awaiting_replydays (1–365, default 3)mail you sent ≥ days ago with no reply (real In-Reply-To/References threading), oldest first, reason awaiting-reply
create_draftto, subject, bodyopens a draft for review — never sends; returns a locator
mail_replymessage_id, mailbox, reply_body, include_quotenative threaded reply (sets In-Reply-To/References) that keeps Mail's own quote, your text on top through Accessibility; opens for review — never sends
drafts—list Mail drafts as pointers (id + subject — to recipient)
delete_draftid, dry_rundelete one draft by message-id; dry_run previews
create_mailboxname (/ nests), accountcreates the folder; missing parents auto-created. No delete counterpart — delete <mailbox> is not scriptable, so removing one is a Mail.app action. In a Gmail account the new folder is a label, which move_mail refuses
move_mailids (≤25), from_mailbox, to_mailbox, dry_runfile/archive/refile; every message backed up + logged before anything moves, so mail_undo puts it back. dry_run defaults to True. Cross-account moves leave exactly one copy. A Gmail label folder is refused at either end (a move out of a label leaves a copy), and so is a unified name as the source
trash_mailids (≤25), mailbox, dry_runsoft delete, and the only delete there is — Mail's delete moves to the account's Trash and nothing in its scripting dictionary erases from there. Undoable via mail_undo; emptying Trash is yours to do in Mail.app. dry_run defaults to True
mail_undoreceipt, dry_runreplay a move_mail/trash_mail receipt in reverse; the undo is itself backed up and undoable. A receipt into a Gmail label or a unified name is refused, with how to restore by hand
update_mail_statusids (≤25), mailbox, read, flagged, flag_colormark read/unread, flag (+colour). Re-issuing with the opposite value is the undo, so dry_run defaults to False
mail_duplicateslimitreport only — per-mailbox redundant-copy counts + worst offenders. Cleanup is the dedupe-mail CLI below; this tool cannot delete
send_mailto, subject, body, cc, bcc, html, from_address, dry_rungated by MACOS_APPS_ALLOW_SEND; dry_run defaults to True
reply_allmessage_id, mailbox, body, include_quote, dry_rungated; native reply-all that keeps Mail's own quote, your text on top through Accessibility; sends only after the text is confirmed, then sweeps its own Drafts copy (drafts_copy)
forward_mailmessage_id, mailbox, to, dry_rungated; original + attachments forwarded intact — no covering-note param (writing the body destroys both, device-verified)

Messages — content via chat.db (read-only; Full Disk Access)

ToolArgsNotes
messages_chats—conversation list (id + name); no content, no FDA needed
messages_searchquery, limitsearch message text (decodes attributedBody), newest first
messages_withcontact (phone/email), country, limitrecent messages with one person; country = calling code or 2-letter region (locale default, never +1)
message_bodyidfull text of one message by guid

Notes — NoteStore.sqlite reads + opt-in bodies

ToolArgsNotes
notestitle, snippet or body words{results, truncated?, plane?, coverage?} — matching notes (id + snippet), title/snippet hits first, then body-only hits; bodies are searched in memory on the Full Disk Access plane (locked notes skipped); body words split at spaces and punctuation only, so a word inside unspaced Chinese or Japanese text is found by title or snippet only; diacritic- & smart-punctuation-insensitive
notes_all—every live note (id + "Account / Folder" + snippet), Recently Deleted excluded
note_bodiesids (≤ 50)opt-in plaintext hydration → [{id, body}]
create_notetitle, body, optional folder namereturns the stable x-coredata id; an unknown/ambiguous folder is refused, not guessed
update_noteid, title, bodyfull replace of title+body by id; the stable id is preserved and verified after write
delete_noteid, expect_title, dry_runmoves to Recently Deleted; dry_run previews

Other read-only context

ToolArgsReturns
contactsname substringcards (name, org, first phone + email)
photossearch string{results, truncated?} pointers (title · filename · date), newest first, at most 25; matches filename, title, description, keywords, place, people and labels. The id is the Photos uuid; the old <UUID>/L0/001 id is still accepted
photo_albums—{results, truncated?} album pointers (id, title (n photos), folder path), at most 100
photo_infophoto iddates, location, place, people, EXIF subset, pixel size, kind; never image bytes or thumbnails
safari_tabs—every open tab (url + title)
shortcutsname substring (empty = all)the user's Shortcuts; id = stable UUID, shortcuts:// deeplink
ping / now / doctor— (doctor takes optional request=True to trigger permission prompts)health check / time / permission diagnostics
auditoptional since (ISO datetime)recent write audit entries (newest first) — what macos-apps-mcp changed, with before/after pointers (enough to undo by hand)
usage—per-tool call counts + the never-used list, for pruning rarely-used tools

Actions (writes)

ToolArgsNotes
create_contactgiven_name, family_name, organization
run_shortcutname or id, optional input_textruns a Shortcut; returns a bounded output snippet
safari_openurlopens in a new tab; bare host → https://; only http/https allowed
export_photophoto id, dest_dir inside the allowed rootwrites the edited still (the original when there is no edit) as a new file, name <original stem>_<id prefix>.<ext>, never overwritten, capped at 250 MiB; a photo only in iCloud is absent (nothing is downloaded); videos refused, a Live Photo exports its still only; additive, audited

Read-only mode

Set MACOS_APPS_READ_ONLY=1 (or true / yes) to register reads only — every write and action tool is skipped, a safe-deploy guard. (Reads may still open apps / read local stores.)

Turning adapters off

Set MACOS_APPS_ADAPTERS_OFF=photos,music (a comma list of adapter names) to register no tools for those apps. Under the daemon, the file ~/.local/state/macos-apps-mcp/adapters_off holds the same list and takes effect after a restart. Details: docs/DAEMON.md.

Dashboard

Under the daemon, http://127.0.0.1:47632 shows the audit trail, Health, the adapter switches, usage and the Mail backups. Run macos-apps-mcp dashboard to open it with its page key. Details: docs/DAEMON.md. Both screenshots use invented data.

[One calendar edit in the dashboard: the old time struck through, the new time beside it, and the exact tool call the model made] [The adapter switches: each app with its permission, its tool count and how often it was called]

Cleaning up duplicate mail

Mail accumulates redundant copies of the same message — a UI drag copies rather than moves, Gmail shows one message under both a label and All Mail, migrations leave copies on two accounts. The read tools already collapse them, so this is only about what is physically on the server. Ask a session for mail_duplicates() to see the damage, then clean up in a terminal:

sh
macos-apps-mcp dedupe-mail                       # preview every mailbox — changes nothingmacos-apps-mcp dedupe-mail --verbose             # also list the sets it will NOT touchmacos-apps-mcp dedupe-mail --execute --mailbox=<folder-url>   # do one mailbox for real

A CLI command, not a tool, for the same reason as allow-send: thousands of deletes against a 30-second-capped serialized worker is hours of work a human starts. It only collapses copies that are byte-identical (size and date sent) — Mail gives no way to address one specific copy, so the survivor is whichever one Mail leaves, and identical bytes are what make that safe. Sets that differ are counted, left alone, and listed under --verbose.

Redundant copies go to Trash, in small batches, each its own mail_undo receipt. Emptying the Trash is yours to do in Mail.app — nothing here can erase a message.

It is slow: ~1 minute per duplicate set against a real IMAP account (Mail's whose lookup scans the whole mailbox), so a big folder is hours. Run it in a terminal you can leave, one mailbox at a time. It is resumable — the plan is recomputed from Mail's index on every run, so interrupting it costs nothing and re-running just finds less to do. A set Mail fails to delete is reported, not retried silently.

Outbound (send) mode

Sending is off by default — the server creates drafts and never sends. Turn it on with:

sh
macos-apps-mcp allow-send mail    # or: messages / mail,messages / all / offmacos-apps-mcp allow-send         # print the current setting

That persists the opt-in and restarts the daemon so it re-registers (registration happens at import, so a restart is unavoidable — reconnect your MCP client afterward). It is a CLI command, not a tool: the gate is your consent, so the model can neither grant itself sending nor restart the server out from under your session.

The same choice is available as MACOS_APPS_ALLOW_SEND in the environment, which is what a stdio server reads (a set variable always wins over the persisted toggle):

ValueEffect
unset (default)no send tools are registered at all
mailMail outbound only (send_mail, reply_all, forward_mail)
mail,messagesnamed adapters (comma list)
1 / true / yes / allevery adapter's outbound

MACOS_APPS_READ_ONLY always wins: with both set, no send tools are registered.

Send tools take dry_run, which defaults to True — deliberately inverted from the id-addressed deletes. A delete targets an item a read already returned; a send constructs its recipient, and a wrong recipient is the failure that matters. The dry run makes no call into Mail at all and reports the resolved envelope; pass dry_run=False to actually send. reply_all is the one exception: its dry run reads (never sends) the original message's actual to/cc recipients, because that's exactly the recipient set a caller can't predict.

A successful send_mail / reply_all / forward_mail result (sent: True) means Mail accepted the message — not that it was delivered. Device-verified: a perfectly-formed message can sit in Mail's Outbox undelivered for minutes after send returns, and a stranded recipient-less message can jam the outbox so later, valid sends queue behind it and never leave. Every result also reports outbox_pending, Mail's current outbox count; when it's greater than zero the result carries a note explaining that delivery is not confirmed and to check Mail ▸ Outbox.

A real reply_all keeps Mail's own quote and takes about a minute: Mail can autosave a copy of the reply into Drafts that survives the send, so the call waits until 45 seconds after the reply window opened and deletes that copy only when it is provably its own. The result's drafts_copy (removed, none, late, unproven or unavailable) and a plain note say what it found; sent stays true whatever that is, and nothing in Sent or All Mail is touched.

Run the doctor tool to check whether sending is actually enabled — deployment.outbound lists every adapter currently send-enabled ([] if none), derived from the same registration logic above rather than a re-read of the raw env var, so it can never disagree with what got registered; deployment.outbound_note explains the state in prose.

Under the daemon deployment, setting MACOS_APPS_ALLOW_SEND in an MCP client's config is a silent no-op: the client's env block reaches the shim, not the long-lived daemon process that reads the variable at import time, and the shipped LaunchAgent plist ships no EnvironmentVariables key. This is exactly why allow-send exists — it writes state the daemon can read (~/.local/state/macos-apps-mcp/allow_send, home-pinned so the shell that writes it and the launchd process that reads it always agree) and survives reboots, unlike launchctl setenv. See docs/DAEMON.md ("Outbound (send) mode under the daemon").

Develop

sh
uv syncuv run pytest                   # unit tests (mock at the adapter boundary)uv run pytest -m integration    # real macOS / EventKit / TCC — run manually, never in CIuv run ruff check .             # lint (config in pyproject.toml)uv run ruff format .            # formatuv run macos-apps-mcp                  # run the server (stdio)

ruff (lint + format, line-length 88) and pytest gate CI — full workflow in CONTRIBUTING.md.

Prior art & credits

macos-apps-mcp builds on prior work — the Apple Mail MCP it draws from, the EventKit/Photos servers it references, the project that pioneered the unified-Apple-MCP pattern, and FastMCP / PyObjC / the MCP spec it depends on. See CREDITS.md.

Source: README.md at commit cb8a1a6

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package did not install.

Version history

1
  1. v0.15.1LatestOct 26, 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