macos-mcp

Local MCP server for macOS native apps: Mail, Calendar, Reminders, Notes, Messages, and Contacts. One stdio process, zero npm dependencies, Node 20+.

Windows and Linux are not supported. Calendar reads use EventKit (bin/eventkit-cal); Calendar writes and other modules use AppleScript/JXA. No Gmail API, no OAuth, no cloud credentials.

What it is

One MCP server = one mental model: read and organize your Mac life.

Email is draft-only. mail_draft_email opens a visible draft in Mail.app; it never sends. You review and send manually.

Related MCP server: apple-mcp

Requirements

• macOS with Mail, Calendar, Reminders, Notes, Messages configured

• Node.js ≥ 20

• Cursor (or any MCP client that supports stdio)

Install

git clone <your-repo-url> macos-mcp
cd macos-mcp
bash scripts/build-eventkit-cal.sh   # required for fast calendar reads
node scripts/install-mcp.js

Restart Cursor. The installer registers macos-local in ~/.cursor/mcp.json (backs up existing config to .bak).

Manual registration:

{
  "mcpServers": {
    "macos-local": {
      "command": "node",
      "args": ["/absolute/path/to/macos-mcp/bin/macos-mcp.js"]
    }
  }
}

Signatures (mail drafts)

bash scripts/install-mail-signatures.sh

Edit signatures/manifest.json and signatures/*.txt locally. Real signatures are gitignored.

macOS permissions

Grant in System Settings → Privacy & Security:

On first calendar read, macOS may prompt for Calendar access. If the helper exits with “Calendar Full Access required”:

1. Open System Settings → Privacy & Security → Calendars

2. Find Cursor (MCP) and/or Terminal (CLI smoke tests)

3. Enable Full Access (not Write Only / Add Only)

4. Re-run npm run smoke:calendar or restart the MCP server

Cursor’s Calendar TCC was previously Write Only on this machine; Full Access is required for EventKit reads. Calendar create/update/delete still use Automation (AppleScript) and do not need EventKit Full Access.

Tool index

Mail (mail_*)

Calendar (calendar_*)

Reminders (reminders_*)

Notes (notes_*)

On newer macOS, note body extraction may fail; notes_get returns body_unavailable: true when scripting is restricted.

Calendar list/search use EventKit (typically under a second for a week range). Create/update/delete still use Calendar.app scripting. Build the helper with npm run build:eventkit if bin/eventkit-cal is missing.

Messages (messages_*)

Requires Full Disk Access. Reads iMessage/SMS locally; no network.

Contacts (contacts_*)

Architecture

bin/macos-mcp.js           → entrypoint
bin/eventkit-cal           → EventKit CLI (built; not committed)
native/EventKitCal/        → Swift source + Info.plist
src/mcp/server.js          → JSON-RPC MCP (protocol 2024-11-05)
src/mcp/transport.js       → stdio NDJSON
src/mcp/tools.js           → aggregates all module tools
src/runtime/eventkit.js    → spawns eventkit-cal for calendar reads
src/runtime/jxa.js         → generic JXA runner (Application per app)
src/runtime/applescript.js → AppleScript runner + draft email
src/mail/                  → Mail module
src/calendar/              → Calendar module (reads → EventKit; writes → AS/JXA)
...

EventKit vs JXA vs AppleScript

• EventKit (bin/eventkit-cal): calendar_list_calendars, calendar_list_events, calendar_search_events.

• JXA (osascript -l JavaScript): read/list/search most other app data; calendar alarm attach after create; generic runJxa(appName, body, args).

• AppleScript: mail_draft_email, calendar create/update/delete/get, and contacts create/update (JXA make is unreliable on modern Calendar.app and Contacts.app).

Response shapes: lists include count; domain keys vary (items, events, reminders, notes, chats, contacts). Errors throw and return MCP isError: true.

Mail.app quirks

• Saved drafts may retain a leading newline Mail adds on save; the compose window is usually correct.

• AppleScript does not auto-attach Mail.app signature prefs; this server appends from signatures/ files instead.

What it is NOT

• No Gmail API, Microsoft Graph, or OAuth

• No auto-send email

• No npm publish (private: true)

• No telemetry or network calls in server code

Development

npm run build:eventkit   # compile bin/eventkit-cal
npm run smoke:calendar   # time calendars + week event list (default 2026-07-27→2026-08-03)
npm start                # stdio server (stderr: [macos-mcp] ready; N tools; macOS only)

Test a tool via MCP client or send JSON-RPC to stdin.

License

MIT