mac-mcp

A read-only MCP server that exposes data from native macOS apps (Mail, Notes, Calendar, Reminders, Contacts, Messages, Spotlight) to AI agents over stdio.

Bootstrapped with Vite+ and Bun. Status: Mail domain shipping; other domains in the pipeline.

Status

The server is read-only by construction. There is no CLI flag, env var, or config key that enables writes. A regression test sweeps every JXA template for write-capable Apple Events phrases (set readStatus, move to, delete, send, etc.) and another sweeps every tool / domain module to ensure they only spawn read-only system commands (osascript, mdfind).

Related MCP server: Machina

Requirements

• macOS 14 or newer (15+ unlocks Apple Mail category support)

• Bun 1.3+

• Full Disk Access granted to your terminal / MCP client (for reading Apple's local data stores)

• Automation permission for Mail.app (granted at first JXA call when listing accounts)

CLI

mac-mcp serve            # start the MCP server over stdio (default)
mac-mcp init             # write ~/.mac-mcp/config.toml template
mac-mcp doctor           # probe macOS permissions, print a checklist
mac-mcp status           # print per-domain index health as JSON
mac-mcp index            # bulk-build domain indexes
mac-mcp rebuild --domain <name>   # rebuild a single domain's index

Mail tools

Nine read-only MCP tools, plus the index://status resource.

Apple Mail category awareness

Mail's built-in categorisation (Primary, Transactions, Updates, Promotions) ships natively on macOS 15+. The server probes the message_global_data.model_category column at startup and degrades cleanly to category-less output on older macOS. The category filter and group_by: "category" both honour this gracefully.

Local index

The Mail domain maintains a SQLite + FTS5 index at ~/.mac-mcp/mail.db:

• WAL mode, synchronous=NORMAL, denormalised is_unread/is_flagged columns for indexed sorts.

• Disk-first state-reconciliation sync (NEW / DELETED / MOVED diffs in pure SQL).

• Background sync every 5 minutes by default (configurable).

• Dead-letter queue surfaces parse failures via index://status.

Spotlight tool

One read-only tool: spotlight_search.

The macOS Spotlight index (mds) is already maintained by the OS; we never build our own. Subprocess runs mdfind with a 5-second per-call timeout; truncated indicates more matches existed beyond the limit.

Contacts tools

Three read-only tools.

Cross-source dedup uses a soft key of (displayName, primaryEmail); collisions keep the source with the higher completeness score and fold the dropped source UUID into the kept record. Phones normalise to E.164 when AddressBook stored the parsed parts (country code + area code + local number); otherwise we strip whitespace and punctuation from the display value. No FTS5 index - LIKE queries against the indexed columns are fast enough at the volumes a personal address book holds.

Calendar tools

Source: ~/Library/Group Containers/group.com.apple.calendar/Calendar.sqlitedb (modern macOS path). Dates round-trip through Core Data's 2001-01-01 epoch.

Reminders tools

Source: one SQLite file per account under ~/Library/Group Containers/group.com.apple.reminders/Container_v1/Stores/. The domain queries every store and merges results.

MCP client config

{
  "mcpServers": {
    "mac": {
      "command": "bunx",
      "args": ["-y", "github:DaniAkash/mac-mcp"]
    }
  }
}

Run mac-mcp doctor after install to verify permissions.

Development

bun install        # install dependencies
bun test           # unit + integration tests (CI-safe; e2e tests skip themselves)
bun run test:e2e   # live end-to-end tests; requires macOS + FDA + Mail.app data
bun run check      # lint + format + fallow code-quality, in parallel
bun run lint       # vp lint (oxlint with full TS typecheck)
bun run fmt        # vp fmt --check
bun run fmt:fix

There is no build step: Bun executes the TypeScript bin (src/bin.ts) directly, both for bun src/bin.ts during development and for consumers via bunx -y github:DaniAkash/mac-mcp. The package ships its src/ directory and Bun handles the rest.

End-to-end tests

tests/e2e/ contains tests that hit the real Mail.app + Envelope Index on the local machine. They require Full Disk Access and a configured Mail account, so they only run when MAC_MCP_E2E=1 is set. CI never sets this env var; the tests skip cleanly on every CI run.

Coverage includes the five Mail tools called directly against the live data (sort order, unread / category / account grouping, multi-account filter, get-email round-trip) plus a full MCP stdio round-trip that spawns the actual mac-mcp serve binary and drives it as a real MCP client over JSON-RPC.

# Grant Full Disk Access to your terminal first.
bun run test:e2e

License

MIT