Macos Mcp

macos-mcp

> Based on FradSer/mcp-server-apple-events

MCP server for Reminders, Calendar, Notes, Mail, Messages, and Contacts on macOS. Local stdio transport — works with any MCP-capable client running on the same Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT desktop, etc.).

> Requires a Mac. This server drives native macOS apps via EventKit, JXA (Apple Events), and SQLite reads of local Apple databases. It cannot run on Linux, Windows, iOS, Android, or in a web browser. You need a Mac (desktop or laptop) running macOS.

Design Notes

• SQLite for reads, JXA for writes. JXA reads of Mail and Messages don't scale — 60s timeouts on real inboxes, and JXA Messages reads are broken entirely on macOS Sonoma+. This server reads chat.db and Mail's Envelope Index directly, including the Gmail labels join table for [Gmail]/All Mail accounts. Writes still go through JXA because Apple Events is the only API that triggers them. See [ADR-001](DECISION.md).
• Per-app hybrid backend. Each app uses the bridge that works: Swift CLI through EventKit for Reminders and Calendar, JXA for Notes/Contacts/Mail-writes/Messages-send, SQLite for Mail and Messages reads. The architecture diagram below shows the full fan-out.
• Cross-tool contact enrichment. A shared layer resolves raw phone numbers and emails to contact names across Messages, Mail, and Calendar. Bulk cache via SQLite AddressBook ( MCP > Add new global MCP server |

| Claude Code | .mcp.json in project root |

Permissions

macOS prompts for access on first use. Click Allow when prompted.

| App | Permission | System Settings Path | |-----|------------|---------------------| | Reminders | Full Access | Privacy & Security > Reminders | | Calendar | Full Access | Privacy & Security > Calendars | | Notes | Automation | Privacy & Security > Automation > Notes | | Mail | Automation + Full Disk Access | Both locations | | Messages | Automation + Full Disk Access | Both locations | | Contacts | Automation | Privacy & Security > Automation > Contacts |

Messages and Mail read SQLite databases directly, so your terminal app (Terminal, iTerm2, etc.) needs Full Disk Access.

Run macos-mcp --check to verify. See [Troubleshooting](#troubleshooting) if anything fails.

Troubleshooting

Quick-Fix Commands

# Open specific settings panes
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Full Disk Access (Messages & Mail)

Messages and Mail read SQLite databases (~/Library/Messages/chat.db and ~/Library/Mail/V10/MailData/Envelope Index). These require Full Disk Access on your terminal app.

# Find your real node binary (version managers use shims)
node -e "console.log(process.execPath)"

# Reveal it in Finder for drag-and-drop into FDA settings
open -R "$(node -e "console.log(process.execPath)")"

# Open Full Disk Access settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"

Version manager users (Volta, nvm, fnm): the node command is a shim. System Settings needs the real binary:

| Manager | Find real binary | |---------|-----------------| | Volta | volta which node | | nvm | nvm which current | | fnm | fnm exec -- node -e "console.log(process.execPath)" |

System Settings may not show binaries in hidden directories — use open -R above to reveal it in Finder, then drag into the FDA list.

JXA Automation (Notes, Mail, Contacts)

On first use, macOS prompts for Automation access. Grant via System Settings > Privacy & Security > Automation.

Verify permissions:

osascript -l JavaScript -e 'Application("Contacts").people().length'
osascript -l JavaScript -e 'Application("Calendar").calendars().length'
osascript -l JavaScript -e 'Application("Reminders").defaultList().name()'
osascript -l JavaScript -e 'Application("Mail").inbox().messages().length'
osascript -l JavaScript -e 'Application("Notes").notes().length'

Each command should return a value. A hang means the permission dialog is trying (and failing) to appear.

Gmail Labels / Missing Inbox Messages

Gmail stores all messages in [Gmail]/All Mail and uses labels for folder membership. The server checks both the direct mailbox and labels join table. If Gmail inbox messages are missing, verify the Mail app has fully synced.

Development

pnpm install          # Install dependencies
pnpm build            # Build TypeScript + Swift binary
pnpm test             # Run full test suite
pnpm lint             # Lint and format (Biome + TypeScript)
pnpm dev              # Run from source via tsx

Production entry point (bin/run.cjs) requires pnpm build. Use pnpm dev for local development.

Architecture

flowchart LR
    Client[MCP ClientClaude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]

    Server --> Swift[Swift CLI]
    Server --> JXA[JXA]
    Server --> SQLite[SQLite Readers]

    Swift -->|EventKit| Reminders[Reminders]
    Swift -->|EventKit| Calendar[Calendar]

    JXA -->|Apple Events| Notes[Notes]
    JXA -->|Apple Events| Contacts[Contacts]
    JXA -->|writes only| Mail[Mail]
    JXA -->|send only| Messages[Messages]

    SQLite -->|Envelope Index| Mail
    SQLite -->|chat.db| Messages
    SQLite -->|AddressBook| Enrich[ContactEnrichment Cache]

Three bridges to Apple apps:

• EventKit (Swift binary) — Reminders, Calendar. Compiled Swift CLI, returns JSON.
• JXA — Notes, Mail writes, Contacts. Scripts run via osascript -l JavaScript.
• SQLite — Messages reads (~/Library/Messages/chat.db), Mail reads (~/Library/Mail/V10/MailData/Envelope Index). JXA message reading is broken on Sonoma+; JXA mail reading is too slow for real inboxes.

Mail and Messages use a hybrid path: JXA for writes (only way to trigger send/draft), SQLite for reads (the only way that scales). See [DECISION.md](DECISION.md) for architecture decision records.

Dependencies

Runtime: @modelcontextprotocol/sdk, zod

Dev: typescript, tsx, jest, @biomejs/biome

License

MIT

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: krmj22
• Source: krmj22/macos-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.