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.

| Tool | Description | |------|-------------| | list-mailboxes | List all mailboxes across all accounts with unread counts | | list-accounts | List configured mail accounts with email addresses and type | | list-signatures | List available email signatures | | search-messages | Search messages by subject or sender (empty query lists all) | | read-message | Read the full content of a specific email | | get-message-source | Get raw RFC822 source of a message | | list-attachments | List attachments on a message with name, MIME type, size | | save-attachment | Save email attachments to disk | | compose-message | Create a draft in Mail.app (does not send) — supports plain or HTML body via htmlBody, plus attachments | | send-message | Send an email immediately (supports from, attachments, plain or HTML body via htmlBody) | | reply-to-message | Reply or reply-all to a message — threads correctly and supports a branded htmlBody or attachments | | forward-message | Forward a message to new recipients | | redirect-message | Redirect a message (preserves original sender) | | move-messages | Move messages between mailboxes | | delete-messages | Delete messages by Message-ID | | mark-as-read | Mark messages as read | | mark-as-junk | Mark/unmark messages as junk | | flag-message | Flag/unflag messages with color support | | set-message-color | Set background color of messages in the message list | | check-for-new-mail | Trigger a mail fetch for one or all accounts | | extract-email-address | Parse "John Doe \<jdoe@example.com\>" into name and address |

Numbers (numbersmcp) — 29 tools

Works with any open Numbers spreadsheet.

| Tool | Description | |------|-------------| | list-spreadsheets | List all open Numbers documents | | create-document | Create a new Numbers document | | list-sheets | List sheets and tables in a document | | get-active-sheet | Get the currently active sheet | | read-range | Read cell values from a range (e.g. "A1:C10") | | read-table | Read an entire table as structured data | | write-cell | Write a value to a specific cell | | write-range | Write multiple values to a range | | clear-range | Clear contents and formatting of a cell range | | get-formula | Get the formula from a cell | | set-formula | Set a formula on a cell | | add-row | Append a row to a table | | delete-row | Delete a row from a table | | add-column | Add a column to a table | | delete-column | Delete a column from a table | | resize-row-column | Set row height or column width | | add-sheet | Add a new sheet to a document | | delete-sheet | Delete a sheet from a document | | rename-sheet | Rename a sheet | | add-table | Add a new table to a sheet | | delete-table | Delete a table from a sheet | | rename-table | Rename a table | | sort-table | Sort a table by a column | | transpose-table | Swap rows and columns of a table | | merge-cells | Merge a range of cells | | unmerge-cells | Unmerge previously merged cells | | set-cell-format | Set cell format (number, currency, date, percentage, etc.) | | set-cell-style | Set font, color, background, bold, italic, alignment | | export-document | Export to PDF, Excel, or CSV |

Contacts (@aernoud/contactsmcp) — 15 tools

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

| Tool | Description | |------|-------------| | search-contacts | Search contacts by name, email, or phone | | search-by-modification-date | Find contacts modified after a given date | | read-contact | Get full contact details | | get-my-card | Get the user's own contact card | | get-vcard | Export a contact as vCard 3.0 text | | create-contact | Create a new contact | | update-contact | Update contact fields | | delete-contact | Delete a contact | | list-groups | List all contact groups | | create-group | Create a new contact group | | rename-group | Rename a contact group | | delete-group | Delete a contact group | | add-to-group | Add a contact to a group | | remove-from-group | Remove a contact from a group | | list-group-members | List all contacts in a group |

Calendar (calendarmcp) — 25 tools

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

| Tool | Description | |------|-------------| | list-calendars | List all calendars with name, writable flag, description | | get-calendar | Get properties of a single calendar by name (incl. event count) | | create-calendar | Create a new calendar | | update-calendar | Rename a calendar or set its description | | delete-calendar | Not supported by Calendar.app — returns a descriptive error; calendars must be removed from the Calendar.app UI | | switch-view | Switch Calendar.app to day/week/month view, optionally jumping to a date | | reload-calendars | Force Calendar.app to refresh from accounts | | list-events | List events in a calendar between two ISO dates | | search-events | Search events by summary substring within a date window (defaults: −30d to +365d). Scope to a single calendar for speed | | get-event | Get full event details by uid | | create-event | Create an event with summary, start, end, optional location/description/url | | update-event | Patch any event field by uid | | delete-event | Delete an event by uid | | move-event | Move an event to another calendar (delete + recreate; new uid) | | duplicate-event | Duplicate an event into the same or another calendar | | today-events | List today's events in one calendar or across all | | upcoming-events | List events in the next N days | | list-attendees | List attendees on an event | | add-attendee | Add an attendee with email and optional display name | | remove-attendee | Remove an attendee by email | | list-alarms | List display, mail, and sound alarms on an event | | add-display-alarm | Add a display alarm N minutes before event start | | add-sound-alarm | Add a sound alarm N minutes before event start | | add-mail-alarm | Add a mail alarm N minutes before event start | | remove-alarm | Remove an alarm by 1-based index from list-alarms output |

Reminders (@aernoud/remindersmcp) — 22 tools

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

| Tool | Description | |------|-------------| | list-accounts | List all accounts in Reminders.app with name and id | | list-lists | List every reminder list, optionally scoped to one account | | get-list | Get properties of a single list (id, account, color, emblem, open + completed counts) | | create-list | Create a new list, optionally in a specific account | | update-list | Rename a list | | delete-list | Delete a list (Reminders.app supports this directly via AppleScript, unlike Calendar.app) | | show-list | Bring a list to the front in Reminders.app | | list-reminders | List reminders in a named list (excludes completed by default) | | search-reminders | Search reminders by name substring; scope to one list for speed | | get-reminder | Get full reminder details by id | | today-reminders | List reminders due today, scoped to one list or all | | upcoming-reminders | List reminders due in the next N days | | overdue-reminders | List reminders past their due date and not yet completed | | create-reminder | Create a reminder with body, due date or all-day due date, remind-me date, priority, flagged | | update-reminder | Patch any reminder field by id | | delete-reminder | Delete a reminder by id | | complete-reminder | Mark a reminder as completed (Reminders auto-stamps completion date) | | uncomplete-reminder | Mark a previously completed reminder as not completed | | move-reminder | Move a reminder to a different list (uses the native move verb — id is preserved) | | flag-reminder | Set or clear the flagged state | | set-priority | Set priority to none / high / medium / low (mapped to Reminders' 0/1/5/9 enum) | | show-reminder | Bring Reminders.app to the front and focus a specific reminder |

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).

| Tool | Description | |------|-------------| | call-phone | Place a cellular call via paired iPhone (tel://) | | call-facetime-audio | Start a FaceTime audio call to a phone number or Apple ID email | | call-facetime-video | Start a FaceTime video call to a phone number or Apple ID email |

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

• 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