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 for compose-message / send-message uses JXA (osascript -l JavaScript) and Mail.app's runtime htmlContent setter on outgoing messages. The plain-text path still uses ordinary AppleScript.

Branded replies that thread correctly

reply-to-message also accepts htmlBody, producing a reply that is both branded and correctly threaded. Mail's scripting model can't set arbitrary RFC headers, and an outgoing reply's rich-text editor isn't writable via the AppleScript content property — so neither tool alone could do both before. The reply tool now:

1. invokes Mail's native reply verb, which constructs the reply and populates the In-Reply-To / References headers (these are message properties, independent of the body), then
2. puts the branded HTML on the pasteboard as public.html and pastes it (Cmd-V) above the auto-quoted thread.

The result renders the branding inline, keeps the quoted thread, and carries the threading headers strict clients (Outlook, Gmail web) require to nest the reply.

// reply-to-message with a branded HTML body
{
  "account": "iCloud",
  "mailbox": "INBOX",
  "messageId": "<abc123@example.com>",
  "body": "Thanks — see below.",       // ignored when htmlBody is set
  "htmlBody": "<p>Thanks for reaching out — here's the update:</p><ul><li><b>Status:</b> shipped</li></ul>"
}

Constraints:

• htmlBody and attachments cannot be combined on a reply (Mail re-parses the HTML during MIME multipart composition and corrupts the rendered body) — the tool returns an error if both are passed. Send the branded reply first, then attach files in a separate reply.
• When htmlBody is supplied, the plain-text body is ignored; Mail derives the plain-text MIME alternative from the pasted rich text.
• Pasting requires Mail to hold focus briefly; the script aborts safely (and restores your clipboard) if focus is lost.

Verifying an HTML / branded reply

After producing a branded reply, confirm both halves actually work:

1. Render check — open the draft Mail created. The branding should appear as formatted rich text (headings, bold, links), not raw <tags>, sitting above the quoted original.
2. Threading / header check — send the reply to a recipient on a strict client (Outlook or Gmail web) and confirm it nests inside the original conversation rather than appearing as a loose message. Equivalently, run get-message-source on the sent reply and verify it carries In-Reply-To: and References: headers pointing at the original Message-ID.
3. Clipboard check — confirm your clipboard holds its prior contents afterwards (the tool saves and restores it around the paste).
4. Attachment guard — calling reply-to-message with both htmlBody and attachments should return a clear error, not a corrupted draft.

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

• For Mail tools taking messageId or messageIds, prefer the numeric string id from search-messages. RFC messageId values remain supported, but comparing them loads message headers across the mailbox and can leave Mail busy even after the 30-second timeout. Local IDs are specific to this Mac's Mail library; search again after moving a message or rebuilding the library.
• 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