macos-apps-mcp

One consolidated MCP server for native macOS apps — Calendar & Reminders read/write, Messages & Notes content search over the native stores, id-first Mail with draft-and-open replies, plus read-only context and a few actions across Contacts, Photos, Safari, and Shortcuts. Python + FastMCP, managed with uv.

Replaces the pile of Apple MCP servers a life-cockpit otherwise juggles with a single modular adapter layer you own. Every read returns pointers (id + one-line summary + open-in-app deeplink), never full bodies — so it structurally avoids the context-bloat bug of the archived flagship server; bodies are a separate, bounded, opt-in fetch.

macOS only. See DESIGN.md for the rationale and CHANGELOG.md for what's landed.

Install

Requires macOS and Python ≥ 3.11.

From source (works today):

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"]
    }
  }
}

From PyPI (once published — see the CHANGELOG): uvx macos-apps-mcp runs the server with no clone, and the MCP config becomes "command": "uvx", "args": ["macos-apps-mcp"] (same "macos-apps" key).

Permissions (macOS TCC)

Grant access when macOS prompts — the first call to each app triggers its dialog:

• EventKit — Calendar + Reminders (read/write).
• Automation (per app) — Mail, Notes, Contacts, Photos, Safari, Messages actions/reads.
• Full Disk Access — required for Messages content (chat.db) and the fast Notes path (NoteStore.sqlite). Notes degrades to Automation without it; Messages content raises a clear, typed error telling you to grant it. Run the doctor tool to see what's granted.

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)

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 subset, e.g. FREQ=WEEKLY;INTERVAL=2;COUNT=10); a recurring reminder needs a due date; unsupported parts (BYDAY, …) are rejected, not ignored.

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.

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

Notes — NoteStore.sqlite reads + opt-in bodies

Other read-only context

Actions (writes)

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

Outbound (send) mode

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

macos-apps-mcp allow-send mail    # or: messages / mail,messages / all / off
macos-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):

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.

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

uv sync
uv run pytest                   # unit tests (mock at the adapter boundary)
uv run pytest -m integration    # real macOS / EventKit / TCC — run manually, never in CI
uv run ruff check .             # lint (config in pyproject.toml)
uv run ruff format .            # format
uv 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.