macos-mail-draft-mcp

An MCP (Model Context Protocol) server that creates email drafts in the macOS Mail app. The server itself runs locally: it drives Mail.app through AppleScript (osascript), opens no network services of its own, and handles no credentials — it never sends an email. Note, however, that Mail owns the draft once it is saved: if the target account is an IMAP, Exchange, or Gmail account (anything other than "On My Mac"), Mail syncs the draft — including its body and attachments — to that account's mail server, just as it would for any draft you create by hand.

Requirements

• macOS with Mail.app configured with at least one account
• Node.js >= 24 (runs the TypeScript source directly — there is no build step and no compiled artifacts; erasableSyntaxOnly keeps the source type-strippable)

Setup

npm install

Register with Claude Code

claude mcp add macos-mail-draft -- node /absolute/path/to/macos-mail-draft-mcp/src/index.ts

Register with Claude Desktop

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

{
  "mcpServers": {
    "macos-mail-draft": {
      "command": "node",
      "args": ["/absolute/path/to/macos-mail-draft-mcp/src/index.ts"]
    }
  }
}

Automation permission

The first time a draft is created, macOS asks the host application (your terminal, Claude Desktop, etc.) for permission to control Mail. If a call fails with "Not authorized to send Apple events", grant access under System Settings > Privacy & Security > Automation.

Tool: create_mail_draft

Creates a draft in Mail's Drafts mailbox. No email is sent. If the draft is saved to a synced account (IMAP / Exchange / Gmail), Mail uploads it to that account's Drafts mailbox on the remote server.

Parameter	Type	Required	Description
to	array of address strings or {address, name}	yes	Primary recipients
subject	string	yes	Subject line
body	string	yes	Plain-text body
cc / bcc	same shape as to	no	CC / BCC recipients
attachments	array of absolute POSIX paths	no	Files to attach (a leading ~ is expanded; files must exist)
sender	email address	no	Account address to send from; defaults to Mail's default account
openComposeWindow	boolean	no	Open the draft in a compose window and bring Mail to the front (default on); false saves silently to Drafts. Attachments are only allowed with the compose window open, so the files being attached are visible for review.

Example call:

{
  "to": [{ "address": "someone@example.com", "name": "Someone" }],
  "subject": "Quarterly report",
  "body": "Hi,\n\nDraft attached.\n\nJason",
  "attachments": ["~/Documents/report.pdf"]
}

Development

npm run dev          # run the server from source (tsx)
npm run check        # typecheck + lint + format check + tests
npm run test:watch   # vitest in watch mode

The AppleScript is generated from validated (zod) input, and every interpolated value is escaped for AppleScript string literals, so recipient names, subjects and bodies cannot break out into script code. Attachment paths are checked to be existing regular files before any script runs.

Known Mail quirks

• Mail silently drops attachments if a draft is saved in the same instant they are added, so the generated script waits one second before saving.
• After saving, the invisible compose session is closed (close ... saving no) so windows don't accumulate. Mail may still keep an inert entry in its scripting outgoing messages list until it is next restarted; this is harmless and invisible.
• Rich text (HTML) bodies are not supported in v1: Mail's AppleScript dictionary cannot set HTML content on an outgoing message, and the available workarounds require GUI scripting via the clipboard.