macOS Apps

macos-apps-mcp

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:

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:

{

"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:

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.

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

uv sync

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

{

"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)

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.

| mail_search | subject, from_, to, mailbox, account, since, until, unread, flagged, has_attachments, body, limit | indexed search via Envelope Index (at rest — no Mail launch unless account= is a display name, which is resolved through Mail; a UUID s