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. All tools talk to local apps via 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: iMCP

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
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 tool call, macOS may prompt for Automation approval per app.

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 queries can be slow (several seconds per calendar) on accounts with large histories. Pass calendar to narrow the search.

Messages (messages_*)

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

Contacts (contacts_*)

Architecture

bin/macos-mcp.js          → entrypoint
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/jxa.js        → generic JXA runner (Application per app)
src/runtime/applescript.js → AppleScript runner + draft email
src/mail/                 → Mail module
src/calendar/             → Calendar module
...

JXA vs AppleScript

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

• AppleScript: mail_draft_email, calendar create/update/delete, 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 start   # runs stdio server (stderr: [macos-mcp] ready; N tools; macOS only)

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

License

MIT