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

Related MCP server: apple-mail-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.

One-time macOS permission grant (Automation)

The first time the server actually calls into Mail.app or Calendar.app, macOS will show a system prompt: "<your terminal/host process> wants to control Mail/Calendar." You must click OK. This is a one-time grant per host-process identity, managed entirely by macOS — no code signing or entitlements needed for this path. If you ever deny it by mistake, re-enable it under:

System Settings → Privacy & Security → Automation → (your terminal/Node host) → Mail / Calendar (toggle on).

If a tool call ever fails with error code AUTOMATION_NOT_AUTHORIZED, this is the setting to check.

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: considered as a Phase 3 stretch goal for Calendar reliability, but not built — event/calendar creation, updates, and attendee-add all worked reliably via JXA in live testing on this machine, better than the pessimistic community reports (Calendar AppleScript scripting has visibly regressed on some recent macOS releases per public reports) the plan was hedging against. Revisit only if a specific operation proves unreliable in practice.

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 — fails on at least some calendars.

• calendar_delete_event on a recurring event — reports success without actually deleting. This is the most important one: it's silently wrong unless caught, which is why every mutating Calendar tool verifies its result before reporting success.

• calendar_remove_attendee — implemented but not live-tested; treat with suspicion until verified.

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

   • Two leftover artifacts from development remain and need manual cleanup since scripting can't remove them (see the confirmed-broken list above): an empty MCP-Delete-Test mailbox in iCloud Mail, and two undeletable recurring test events in the MCP-Scratch calendar.

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