Macos MCP Server

macos-mcp

MCP servers for macOS native apps — gives Claude Code, Claude Desktop, and any MCP client native access to Mail, Numbers, Contacts, Calendar, Reminders, and FaceTime / phone calls.

No API keys, no OAuth, no cloud services. Talks directly to macOS apps via AppleScript and URL schemes (tel://, facetime://). Runs locally on your Mac.

CUPS printing (printmcp) used to live here; it moved to office-mcp since it's a shell wrapper, not an AppleScript bridge.

Servers

Mail (mailappmcp) — 21 tools

Works with every email account configured in Mail.app — iCloud, Gmail, Outlook, Fastmail, you name it.

Numbers (numbersmcp) — 29 tools

Works with any open Numbers spreadsheet.

Contacts (@aernoud/contactsmcp) — 15 tools

Works with the system address book — all accounts synced to Contacts.app.

Calendar (calendarmcp) — 25 tools

Works with every calendar configured in Calendar.app — iCloud, Google, Exchange, local, you name it.

Reminders (@aernoud/remindersmcp) — 22 tools

Works with every reminder list configured in Reminders.app — iCloud, Exchange, local, you name it.

FaceTime (facetimemcp) — 3 tools

Initiates calls by handing URL schemes to open. Phone calls require an iPhone paired via Continuity (so macOS can route them through your phone).

Phone numbers are normalized + validated as E.164 (+15551234567); spaces, dashes, and parens are tolerated. macOS may show a confirmation prompt before dialing — there is no fully silent dial path, by design.

Requirements

• macOS (uses AppleScript — won't work on Linux/Windows)
• Node.js 18+

Install

From npm

npm install -g mailappmcp            # Mail server
npm install -g numbersmcp            # Numbers server
npm install -g @aernoud/contactsmcp  # Contacts server
npm install -g @aernoud/calendarmcp  # Calendar server
npm install -g @aernoud/remindersmcp # Reminders server
npm install -g @aernoud/facetimemcp  # FaceTime / phone calls

From source

git clone https://github.com/aernouddekker/macos-mcp.git
cd macos-mcp
npm install
npm run build

Configure

Claude Code

Add to ~/.claude/settings.json or your project's .mcp.json:

{
  "mcpServers": {
    "mailappmcp":   { "command": "npx", "args": ["-y", "mailappmcp"] },
    "numbersmcp":   { "command": "npx", "args": ["-y", "numbersmcp"] },
    "contactsmcp":  { "command": "npx", "args": ["-y", "@aernoud/contactsmcp"] },
    "calendarmcp":  { "command": "npx", "args": ["-y", "@aernoud/calendarmcp"] },
    "remindersmcp": { "command": "npx", "args": ["-y", "@aernoud/remindersmcp"] },
    "facetimemcp":  { "command": "npx", "args": ["-y", "@aernoud/facetimemcp"] }
  }
}

Claude Desktop / Cowork

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mailappmcp":   { "command": "npx", "args": ["-y", "mailappmcp"] },
    "numbersmcp":   { "command": "npx", "args": ["-y", "numbersmcp"] },
    "contactsmcp":  { "command": "npx", "args": ["-y", "@aernoud/contactsmcp"] },
    "calendarmcp":  { "command": "npx", "args": ["-y", "@aernoud/calendarmcp"] },
    "remindersmcp": { "command": "npx", "args": ["-y", "@aernoud/remindersmcp"] },
    "facetimemcp":  { "command": "npx", "args": ["-y", "@aernoud/facetimemcp"] }
  }
}

How it works

Each server runs locally over stdio. The Mail, Numbers, and Contacts servers build AppleScript strings, execute them via osascript, and parse the structured output back into JSON. The Print server shells out to CUPS (lp, lpstat, lpoptions, cancel); the FaceTime server hands tel:// / facetime:// URLs to open. A shared package (@mailappmcp/shared) provides the AppleScript runner, the generic command runner (runCommand), string escaping, and delimiter-based parsing.

App lifecycle — leave as found

Mail, Calendar, Contacts, and Reminders need their respective app running to respond to AppleScript. Rather than requiring you to keep those apps open, each server auto-launches them on first use and cleans up afterwards:

• On the first tool call that touches an app, the server checks (via pgrep) whether the app is already running. If not, it launches it in the background (open -g -a) without stealing focus, and waits up to 5 seconds for the app to accept AppleEvents before running the tool.
• That state is remembered in-process for the lifetime of the MCP server. Subsequent tool calls against the same app skip the probe and reuse the running app — no repeated launch penalty.
• On server shutdown (SIGTERM / SIGINT / SIGHUP / normal exit — e.g. when Claude Desktop disconnects the server or the chat ends), the server quits only the apps it launched. Apps you had open before the server started are left alone.
• Edge case: if the server is force-killed (SIGKILL), the exit handler can't run, so any auto-launched apps stay running. Same as if you'd never had the server.

This means you can use the tools without worrying about a pile of half-launched apps lingering after the session, and without the servers killing apps you were actively using.

Safety

• compose-message opens a visible draft — you review before sending
• send-message is a separate, explicit action
• reply-to-message and forward-message default to draft mode (sendImmediately: false)
• delete-messages moves to Trash (standard Mail.app behavior)

HTML email

compose-message and send-message accept an optional htmlBody parameter. When supplied, the message is created as a rich-text/HTML message and the recipient sees rendered formatting (headings, bold, lists, clickable links) instead of raw tags. body is still required and is used as the plain-text fallback for clients that read plain content. Omit htmlBody for the existing plain-text behavior — fully backward compatible.

// send-message with HTML body
{
  "to": ["alice@example.com"],
  "subject": "Weekly update",
  "body": "Highlights:\n- Shipped feature X\n- Fixed bug Y",
  "htmlBody": "<h2>Highlights</h2><ul><li>Shipped <b>feature X</b></li><li>Fixed bug Y — see <a href=\"https://example.com/issue/42\">#42</a></li></ul>"
}

Under the hood, the HTML path uses JXA (osascript -l JavaScript) and Mail.app's runtime htmlContent setter on outgoing messages. The plain-text path still uses ordinary AppleScript.

Known limitations

General

• osascript has a 30-second timeout per call
• Apps are auto-launched on first use and quit on server shutdown if they weren't running beforehand — see App lifecycle

Mail

• content contains searches in AppleScript can be slow on large mailboxes — Mail server searches subject and sender by default

Numbers

• Numbers tools require an open document

Calendar

These are limitations of Calendar.app's AppleScript interface itself, not the MCP server:

• Calendars cannot be deleted via AppleScript. delete calendar raises -10000 (AppleEvent handler failed) on every modern macOS version. The delete-calendar tool checks that the calendar exists and then returns a descriptive error — you must remove calendars manually from the Calendar.app sidebar (right-click → Delete).
• Calendars have no usable id/uid. Calendar.app's calendar class does not expose a stable id via AppleScript (uid of raises -10000). All calendar tools therefore identify calendars by name — make sure your calendar names are unique.
• whose filters are O(n) over events. AppleScript scans every event in a calendar to evaluate whose start date ≥ X predicates. On a busy multi-calendar store, even an empty 7-day query across all calendars can take 60+ seconds and exceed the 30 s osascript timeout. Always pass a calendarName to list-events, search-events, today-events, and upcoming-events when possible to scope the scan. search-events additionally enforces a date window (default: −30 days to +365 days).
• move-event reassigns the uid. Calendar.app cannot reparent an event between calendars. The tool deletes the source event and creates a new one in the target calendar; the new event has a fresh uid (returned as newUid alongside oldUid).
• Recurrence is exposed as raw RRULE strings (e.g. FREQ=WEEKLY;INTERVAL=1) — read and write only, no parsing or expansion.

License

MIT