mac-mcp

One consolidated MCP server for native macOS apps — Calendar & Reminders read/write, plus read-only context and a few actions across Mail, Notes, Contacts, Photos, Safari, Messages, and Shortcuts. Python + FastMCP 2.0, managed with uv.

Replaces the two Apple MCP servers a life-cockpit otherwise juggles (apple-events + a forked Apple Mail MCP) 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.

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

Tools

Reads return pointers; results are capped per adapter. Writes/actions are skipped entirely when MAC_MCP_READ_ONLY is set (see below).

Calendar & Reminders — read/write (EventKit)

Recurrence is an RFC 5545 RRULE string — the FREQ / INTERVAL / COUNT / UNTIL subset (e.g. FREQ=WEEKLY;INTERVAL=2;COUNT=10). A recurring reminder requires a due date; unsupported parts (BYDAY, …) are rejected rather than silently ignored.

Read-only context (AppleScript / CLI)

Actions (writes)

Read-only mode

Set MAC_MCP_READ_ONLY=1 (or true / yes) to register reads only — every write and action tool above is skipped, a safe-deploy guard.

Related MCP server: nucleus-apple-mcp

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 mac-mcp            # run the server (stdio)

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

Use as an MCP server

Launch off the project's own venv python — deterministic, and it carries the locked PyObjC wheels:

{
  "mcpServers": {
    "mac-mcp": {
      "command": "/Users/you/Developer/mac-mcp/.venv/bin/python",
      "args": ["-m", "mac_mcp"]
    }
  }
}

macOS only. Calendar/Reminders use EventKit; the other adapters script their apps via Automation. Grant access when macOS prompts (TCC) — the first call to each app triggers its permission dialog.

Prior art & credits

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