macos-mail-mcp

An MCP server for Apple Mail (macOS Mail.app) that connects Claude to your email via AppleScript. Provides 20 tools for reading, searching, managing, and composing emails.

Supported Accounts

Works with any email account configured in macOS Mail.app — iCloud, Gmail, Outlook/Exchange, Yahoo, Fastmail, custom IMAP/POP, etc. No code changes needed; just add the account in Mail.app and it becomes available through all 20 tools.

Requirements

• macOS with Mail.app configured (with at least one email account)
• Node.js 18+
• Claude Code or Claude Desktop app

Installation

Quick Install (npm)

The easiest way — no cloning or building required.

Claude Code and Claude Desktop use separate MCP configs. The claude mcp add command below configures Claude Code only — it writes to ~/.claude.json. Claude Desktop and Cowork read a different file (claude_desktop_config.json) and must be configured separately. Set up whichever you use, or both.

Claude Code (CLI):

claude mcp add --scope user macos-mail-mcp -- npx -y macos-mail-mcp

--scope user makes the server available in every project — the default local scope only registers it for the directory you run the command in. -y lets npx install the package on first run without an interactive prompt.

Claude Desktop (and Cowork):

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

{
  "mcpServers": {
    "macos-mail-mcp": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "macos-mail-mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}

Use the absolute path to npx — GUI apps don't inherit your shell's PATH, so a bare "npx" usually fails to launch. Find yours with which npx:

• Apple Silicon Homebrew: /opt/homebrew/bin/npx
• Intel Homebrew: /usr/local/bin/npx
• nvm: ~/.nvm/versions/node/<version>/bin/npx

The env.PATH entry lets npx locate node for the same reason. Then fully quit Claude (Cmd+Q — closing the window isn't enough) and reopen; the config is only read at startup. If the server doesn't appear, check ~/Library/Logs/Claude/mcp*.log for spawn errors.

Install from Source

If you prefer to build locally or want to contribute:

git clone https://github.com/marius-cetanas/macos-mail-mcp.git
cd macos-mail-mcp
npm install
npm run build

Then register with Claude Code:

claude mcp add --transport stdio --scope user macos-mail-mcp -- node /path/to/macos-mail-mcp/build/index.js

Or add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "macos-mail-mcp": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/path/to/macos-mail-mcp/build/index.js"]
    }
  }
}

Use the absolute path to node here too (find yours with which node) — same PATH reason as above. Then fully quit and reopen Claude.

macOS Permissions

On first use, macOS will prompt to grant automation permission for controlling Mail.app. Go to System Settings > Privacy & Security > Automation to manage this.

Tools

Accounts (2)

Tool	Description
list_accounts	List all mail accounts (name, type, enabled, emails)
get_account_detail	Get full account details (server, port, SSL, mailbox count)

Mailboxes (3)

Tool	Description
list_mailboxes	List mailboxes for an account or all accounts
get_mailbox_info	Get mailbox details (message count, unread count)
create_mailbox	Create a new mailbox (top-level or nested under a parent)

Messages (8)

Tool	Description
list_messages	List messages with pagination (limit/offset) and optional date filtering (after/before)
get_message	Get full message content, headers, recipients, attachments. Mailbox name is optional — omit to search all mailboxes in the account.
search_messages	Search by subject, sender, or content with optional date filtering (after/before). Results include the mailbox name.
move_message	Move a message to a different mailbox
move_messages	Bulk move multiple messages to a different mailbox in a single operation
delete_message	Delete a message (moves to Trash)
flag_message	Set/clear flag with optional color index (0-6)
mark_read	Mark message as read or unread

Attachments (4)

Tool	Description
list_attachments	List attachments with filename, MIME type, size, download status
save_attachment	Save a specific attachment to disk
save_all_attachments	Save all attachments from a message
read_attachment	Read text-based attachment content inline (.txt, .csv, .json, .html, .md, .xml, .log)

Compose (3)

Tool	Description
send_message	Send a new email with optional CC, BCC, and attachments
reply_to_message	Reply or reply-all to a message
forward_message	Forward a message to a new recipient

Architecture

src/
  index.ts                          # MCP server entry point
  types.ts                          # TypeScript interfaces
  utils.ts                          # Shared utilities (sanitize, expandTilde, toolError)
  bridge/
    applescript-runner.ts            # AppleScript execution engine
    escape-for-json.applescript      # Shared JSON escaping handler (auto-prepended)
  domains/
    accounts/
      accounts.tools.ts             # Tool registration & handlers
      scripts/*.applescript          # AppleScript templates
    mailboxes/
      mailboxes.tools.ts
      scripts/*.applescript
    messages/
      messages.tools.ts
      scripts/*.applescript
    compose/
      compose.tools.ts
      scripts/*.applescript
tests/
  utils.test.ts                     # Shared utility tests
  bridge/applescript-runner.test.ts  # Bridge unit tests
  domains/*/                         # Domain handler tests

Domain-driven layered architecture:

• Tools layer — Registers MCP tools with Zod schemas, validates input, calls the bridge
• Bridge layer — Reads AppleScript templates, substitutes parameters (with injection-safe escaping), prepends the shared escapeForJson handler, executes via osascript, parses JSON output
• Script layer — AppleScript templates with {{param}} placeholders, returning JSON strings. The escapeForJson handler is defined once in bridge/escape-for-json.applescript and automatically prepended to every script at runtime.

Known Limitations

AppleScript Foundation

This MCP communicates with Mail.app via AppleScript, which is a stable but legacy automation layer. Mail.app's scripting dictionary has been largely unchanged for years, but future macOS updates could require script adjustments. This is an inherent trade-off of the approach — AppleScript is the only officially supported way to automate Mail.app without writing a native plugin.

Performance

• Large mailbox searches — search_messages uses Mail.app's whose clause, which performs a linear scan and loads all matching messages into memory before applying the limit. Searching by content (message bodies) on very large IMAP mailboxes (50K+ messages) can be slow or timeout. Prefer searching by subject or sender when possible, and narrow results with accountName and mailboxName.
• IMAP attachment downloads — Attachments on IMAP accounts may not be downloaded locally. The tools check download status and report clearly when an attachment needs to be opened in Mail.app first.

Message IDs

Mail.app's internal message IDs are volatile — they can change when the app reindexes, or after move/delete operations. This means multi-step workflows (e.g., list → flag → move) should re-fetch message IDs between mutations. For single-step operations this is not an issue.

Provider-Specific Behavior

• Exchange accounts — Server details (hostname, port, SSL) are not exposed via AppleScript for Exchange/EWS accounts. Mailbox and message operations work normally.
• Gmail labels — move_message adds the destination label but may not remove the original (Gmail uses labels, not folders).

Other Limitations

• Attachments on replies/forwards — AppleScript does not support adding new attachments to reply/forward messages (Mail.app limitation).
• MIME type detection — Uses extension-based fallback when Mail.app's native MIME type property returns missing value.
• Mailbox management — Creating mailboxes is supported, but deleting and renaming mailboxes is not possible via AppleScript (Mail.app limitation).

Roadmap

• get_thread — Retrieve all messages in a conversation thread. Mail.app has no native threading support; implementation would require parsing RFC headers (Message-ID, In-Reply-To, References) which is slow on large mailboxes. Planned for v2.

Development

npm run dev          # Watch mode (TypeScript compiler)
npm test             # Run tests
npm run test:watch   # Watch mode tests
npm run build        # Build for production

License

MIT