mail-calendar-mcp

A local MCP server giving full read/write control over Apple Mail.app and Calendar.app on macOS — every account configured in either app (iCloud, Google, Exchange, IMAP, etc.) is exposed uniformly, with no per-provider setup and no GUI/computer-use automation. All automation is done via JXA (osascript -l JavaScript) talking to the same AppleScript dictionaries Mail.app/Calendar.app themselves expose.

Status

Feature-complete: all of Mail and Calendar's core scriptable surface is implemented, plus computed availability. Every tool below was exercised through the real MCP protocol against a live Mail.app/Calendar.app during development, not just type-checked — several real bugs were found and fixed or explicitly documented as platform limitations in the process (see below).

Calendar runs on a native EventKit backend by default (helper/main.swift, compiled to bin/calendar-helper by npm run build). This exists because Calendar.app's AppleScript bridge silently no-ops on several operations. The native backend fixes the confirmed recurring-event-delete and calendar-delete bugs, and adds capabilities AppleScript cannot express at all: per-occurrence vs whole-series edits/deletes (occurrenceDate + span), stable calendarIds, calendar source selection, richer event detail (attendees/alarms/detached-occurrence status), and cross-calendar queries in one call. If the helper binary is missing or lacks Calendar permission, calendar tools fall back to the JXA path automatically (safe even for writes — the permission check runs before any operation). MCM_CALENDAR_BACKEND=jxa forces the old path. Mail remains JXA-only: there is no public native API for Mail.app automation.

Related MCP server: calendar-mcp

Tool inventory

Mail

Calendar

Cross-cutting

Setup

npm install
npm run build   # or `npm run dev` for a live tsx run during development
npm test        # runs the vitest suite (Node-side logic only, see Testing below)

Add to your MCP client config (Claude Desktop / Claude Code) pointing at dist/index.js (after npm run build) or src/index.ts via npx tsx for development.

Building requires the Xcode Command Line Tools (swiftc) for the native calendar helper.

One-time macOS permission grants

Two separate macOS permissions are involved (both one-time, both per host app — the app that spawns the server, e.g. Claude Desktop or your terminal):

1. Automation (Mail + Calendar via JXA): the first JXA call triggers "<host> wants to control Mail/Calendar" — click OK. Re-enable under System Settings → Privacy & Security → Automation if ever denied.

2. Calendars — Full Access (native EventKit backend): the host app needs Full Access under System Settings → Privacy & Security → Calendars. Note macOS may silently grant only "Add Events Only" without ever prompting — if calendar_app_status reports the helper unauthorized, flip that entry to Full Access manually. Until then, calendar tools transparently fall back to JXA.

If a tool call fails with error code AUTOMATION_NOT_AUTHORIZED, these are the settings to check. The ad-hoc code signature on bin/calendar-helper changes on every rebuild, which can re-trigger the Calendars grant.

Important gotcha: fromAddress

Creating a draft or sending without specifying fromAddress silently uses Mail.app's global default "send new messages from" account — confirmed during development that this is not necessarily the account you intended (on the development machine it defaulted to an unrelated work account rather than the personal account being targeted). fromAddress is a required field on mail_create_draft and on mail_send_message when composing fresh (not required when sending an existing composeSessionId, which already has an account fixed).

Design notes

• Injection-safe: every JXA invocation uses execFile('osascript', ['-l','JavaScript', <fixed script path>, <JSON string>]) — never a shell string, never AppleScript source built from caller input. See src/jxa/runner.ts.

• Timeouts: every call has a per-operation timeout with SIGKILL on expiry, since Mail/Calendar can hang against an offline/asleep account or an unbounded query. Verified against both a deliberately-hung script and a real unbounded Calendar query during development.

• Error taxonomy: see src/errors.ts — tool failures return one of a fixed set of codes (APP_NOT_RUNNING, AUTOMATION_NOT_AUTHORIZED, ACCOUNT_OFFLINE_OR_ASLEEP, NOT_FOUND, TIMEOUT, PLATFORM_LIMITATION, INVALID_INPUT, UNEXPECTED_OSA_ERROR) rather than opaque strings. PLATFORM_LIMITATION specifically covers writes that report success but don't actually take effect — caught by re-reading state after every mutating call.

• Destructive-tool gating: the highest-risk tools (permanent delete, send, delete calendar/mailbox) require an explicit confirm: true argument in addition to whatever gating your MCP client applies, as defense-in-depth against an accidental or hallucinated call. See requireConfirm() in src/tools/register.ts.

• Object identity: Mail messages are addressed by {accountName, mailboxPath, messageId} (Mail's internal numeric id) or by RFC822 Message-ID; mailboxes by hierarchical name path; Calendar events by their iCalendar uid (stable via scripting, unlike calendars themselves, which have no queryable uid — hence the calendarIndex disambiguator).

• Native Swift/EventKit helper: originally deferred (most JXA calendar operations worked in initial testing), later built once the JXA bridge's failures proved painful in real use — see the Status section. helper/main.swift is a single-file CLI compiled by npm run build:helper with an embedded Info.plist (linker -sectcreate) and an ad-hoc code signature; it speaks the same JSON-envelope contract as the JXA scripts, so src/helper/backend.ts can route per-call with JXA fallback. EventKit's public API cannot write attendees, so attendee add/remove stays on JXA regardless of backend.

Known permanent platform limitations

(Not bugs — confirmed not achievable via AppleScript/JXA, and in most cases no alternative API exists either.)

• Mail: creating/editing Mail rules (rules can only invoke a script as an action, not be created externally — mail_list_rules is read-only by design); mail account creation/credential management.

• Calendar: sending or RSVP-replying to meeting invitations; to-dos (moved entirely to Reminders.app, a separate app/dictionary, out of scope here).

Known confirmed-broken/flaky operations

(Found via live testing, not guessed — reproduced deterministically before being documented.)

• mail_rename_mailbox — the property assignment is rejected outright.

• mail_delete_mailbox — fails on cloud-synced accounts (confirmed on iCloud); untested on local mailboxes.

• mail_add_attachment_to_draft — syntax unverified, no live test possible; treat with suspicion.

• calendar_delete_calendar — fixed by the EventKit backend; the JXA fallback remains broken.

• calendar_delete_event on a recurring event — fixed by the EventKit backend; the JXA fallback reports success without actually deleting (silently wrong unless caught, which is why the JXA path verifies its result before reporting success).

• calendar_remove_attendee — implemented but not live-tested; treat with suspicion until verified. (EventKit's public API cannot write attendees at all, so this stays on JXA regardless of backend.)

Testing

There's no way to unit-test "did this actually change Mail.app/Calendar.app state" outside a live session, so verification is two-tiered:

1. Manual checklists (test/manual-checklists/) — the primary verification method, run against dedicated scratch fixtures so destructive-op testing never touches real mail/events:

   • Mail: a Testing/MCP-Scratch mailbox on a non-work account, all send-tests target only your own address.

   • Calendar: a local MCP-Scratch calendar ("On My Mac", to avoid sync churn).

   • One leftover artifact from development still needs manual cleanup: an empty MCP-Delete-Test mailbox in iCloud Mail (mailbox deletion via scripting is broken, see above). Two recurring test events stuck in the MCP-Scratch calendar — the JXA delete bug's own evidence — are removable via the EventKit backend.

2. npm test (vitest) — covers only the Node-side logic that doesn't need live app state: error-code mapping (test/errors.test.ts), destructive-tool confirm-gating (test/register.test.ts), JSON envelope parsing robustness (test/jxa-runner.test.ts), and free/busy gap computation (test/availability.test.ts).