macos-mcp

Drive Reminders, Calendar, Notes, Mail, Messages, and Contacts on macOS from an AI agent, or from the shell.

Apple exposes three automation surfaces for these apps, and each one fails somewhere. EventKit does not reach Notes, Mail, Messages, or Contacts. JXA reads of Messages return nothing on Sonoma and later. JXA reads of Mail time out at 60 seconds against a real inbox. This project uses the bridge that works per app and documents why in DECISION.md.

App	Reads	Writes
Reminders	EventKit (Swift)	EventKit (Swift)
Calendar	EventKit (Swift)	EventKit (Swift)
Notes	JXA	JXA
Contacts	JXA	JXA
Mail	SQLite (`Envelope Index`)	JXA
Messages	SQLite (`chat.db`)	JXA

Requires a Mac. These bridges are EventKit, Apple Events, and SQLite reads of local Apple databases. There is no Linux, Windows, iOS, Android, or browser build.

Three ways to use it

As an MCP server. Local stdio transport, works with any MCP-capable client on the same Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT desktop). Eight tools, listed under Tools.

As an agent skill. The same bridges called as shell commands, with no tool schemas loaded into context. An MCP server puts all eight tool definitions in front of the model at session start whether or not the session touches a Mac app; a skill is one description line until something triggers it. See skills/macos/ for the skill, and docs/mcp-vs-skill.md for how to choose.

As a CLI. EventKitCLI is a standalone Swift binary that speaks JSON on stdout. The JXA and SQLite recipes in the skill run anywhere a shell does.

Quick Start

Install as a Claude Code plugin

/plugin marketplace add krmj22/macos-mcp
/plugin install macos-mcp@krmj22-plugins

Run these inside Claude Code. The plugin wires up the MCP server via npx -y mcp-macos, so no separate install step is required.

Install from npm

npm install -g mcp-macos
# or use npx via your client's MCP config (no global install needed)

Or install via MCPB (Claude Desktop)

Download the .mcpb bundle from the latest GitHub release and drag it onto Claude Desktop. The bundle includes a pre-built universal Swift binary (arm64 + x86_64), so no Xcode Command Line Tools required.

Or build from source

git clone https://github.com/krmj22/macos-mcp.git
cd macos-mcp
pnpm install
pnpm build

Verify setup

macos-mcp --check   # or: node dist/index.js --check

Checks macOS version, Node.js, EventKit binary, Full Disk Access, and JXA automation permissions.

Or use it as a skill instead of a server

Copy the skill into your agent's skills directory. No MCP server, no tool schemas in context.

git clone https://github.com/krmj22/macos-mcp.git
cp -R macos-mcp/skills/macos ~/.claude/skills/macos

The skill calls EventKitCLI, osascript, and sqlite3 directly, so it needs the Swift binary on PATH:

cd "$(mktemp -d)" && npm i mcp-macos --no-save \
  && mkdir -p ~/.local/lib/mcp-macos/bin \
  && cp node_modules/mcp-macos/bin/EventKitCLI ~/.local/lib/mcp-macos/bin/EventKitCLI \
  && ln -sf ~/.local/lib/mcp-macos/bin/EventKitCLI ~/.local/bin/EventKitCLI

Same permissions apply either way. See Permissions.

Tools

Tool	App	Bridge	Actions
`reminders_tasks`	Reminders	EventKit	read, create, update, delete
`reminders_lists`	Reminders	EventKit	read, create, update, delete
`calendar_events`	Calendar	EventKit	read, create, update, delete
`calendar_calendars`	Calendar	EventKit	read
`notes_items`	Notes	JXA	read, create, update, delete
`notes_folders`	Notes	JXA	read, create
`mail_messages`	Mail	SQLite + JXA	read, create, update, delete
`messages_chat`	Messages	SQLite + JXA	read, create
`contacts_people`	Contacts	JXA	read, search, create, update, delete

Both underscore (reminders_tasks) and dot (reminders.tasks) notation work.

Design Notes

SQLite for reads, JXA for writes. JXA reads of Mail do not scale, hitting 60s timeouts on real inboxes, and JXA Messages reads are broken entirely on macOS Sonoma and later. This project 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.
Per-app hybrid backend. Each app uses the bridge that works: a Swift CLI through EventKit for Reminders and Calendar, JXA for Notes, Contacts, Mail writes and Messages send, SQLite for Mail and Messages reads. The architecture diagram shows the fan-out.
Cross-tool contact enrichment. A shared layer resolves raw phone numbers and email addresses to contact names across Messages, Mail, and Calendar. Bulk cache via the SQLite AddressBook store, under 50ms for 1,100 entries; targeted lookups via JXA whose(). See ADR-002.
Preflight check. macos-mcp --check validates macOS version, Node.js, the EventKit binary, Full Disk Access, and JXA permissions before runtime, with deep links to the relevant System Settings panes for anything that fails.

Setup

Prerequisites

Node.js 20+
macOS
Xcode Command Line Tools (Swift compilation)

Client Configuration

The JSON config is the same for all clients. Only the location differs.

{
  "mcpServers": {
    "macos-mcp": {
      "command": "npx",
      "args": ["mcp-macos"]
    }
  }
}

Client	Config location
Claude Desktop	`claude_desktop_config.json`
Cursor	Settings > 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 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 Client<br/>Claude 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[Contact<br/>Enrichment 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 and later. 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 for architecture decision records.

Dependencies

Runtime: @modelcontextprotocol/sdk, zod

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

Credits

The MCP server layer started from FradSer/mcp-server-apple-events (MIT). The EventKit Swift CLI, the SQLite read paths, contact enrichment, the preflight check, and the skill surface were added here.

License

MIT

Contributing

See CONTRIBUTING.md.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.github		.github
bin		bin
docs		docs
mcpb		mcpb
scripts		scripts
skills/macos		skills/macos
src		src
tests/e2e		tests/e2e
.gitignore		.gitignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DECISION.md		DECISION.md
LICENSE		LICENSE
README.md		README.md
babel.config.cjs		babel.config.cjs
biome.json		biome.json
jest-env.cjs		jest-env.cjs
jest.config.mjs		jest.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

macos-mcp

Three ways to use it

Quick Start

Install as a Claude Code plugin

Install from npm

Or install via MCPB (Claude Desktop)

Or build from source

Verify setup

Or use it as a skill instead of a server

Tools

Design Notes

Setup

Prerequisites

Client Configuration

Permissions

Troubleshooting

Quick-Fix Commands

Full Disk Access (Messages & Mail)

JXA Automation (Notes, Mail, Contacts)

Gmail Labels / Missing Inbox Messages

Development

Architecture

Dependencies

Credits

License

Contributing

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

macos-mcp

Three ways to use it

Quick Start

Install as a Claude Code plugin

Install from npm

Or install via MCPB (Claude Desktop)

Or build from source

Verify setup

Or use it as a skill instead of a server

Tools

Design Notes

Setup

Prerequisites

Client Configuration

Permissions

Troubleshooting

Quick-Fix Commands

Full Disk Access (Messages & Mail)

JXA Automation (Notes, Mail, Contacts)

Gmail Labels / Missing Inbox Messages

Development

Architecture

Dependencies

Credits

License

Contributing

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages