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.

Related MCP server: mail-mcp

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)

Mailboxes (3)

Messages (8)

Attachments (4)

Compose (3)

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