MCP Apple Mail

MCP Apple Mail Desktop Extension

A desktop extension for Claude that provides seamless Apple Mail integration through the Model Context Protocol (MCP) using JXA (JavaScript for Automation).

Features

✨ No String Parsing - Uses JXA to return native JavaScript objects 🎯 Type-Safe - Full TypeScript support with interfaces 📧 Complete Mail Support - Read, search, send, manage emails 🔐 Account-Specific Sending - Send from any configured account 📁 Hierarchical Mailboxes - Full mailbox tree structure support

Installation

As a Desktop Extension (Recommended)

Download the apple-mail.mcpb extension package
Double-click to install in Claude Desktop
Configure your preferences in the Claude Desktop settings

Manual Installation

For development or manual setup:

# Clone the repository
git clone https://github.com/LionSR/mcp-apple-mail
cd mcp-apple-mail

# Install dependencies
npm install

# Build the extension
npm run build

# Create the MCPB package
npm run pack

Then add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/path/to/mcp-apple/dist/index.js"],
      "env": {
        "MAIL_ENABLED_ACCOUNTS": "${user_config.enabled_accounts}",
        "MAIL_DISABLED_ACCOUNTS": "${user_config.disabled_accounts}",
        "MAIL_SEARCH_DEFAULT_LIMIT": "${user_config.search_limit}",
        "MAIL_PRIORITY_MAILBOXES": "${user_config.priority_mailboxes}",
        "MAIL_JXA_TIMEOUT": "${user_config.jxa_timeout}",
        "MAIL_MAX_MAILBOXES_CHECK": "${user_config.max_mailboxes_check}",
        "MAIL_MESSAGES_PER_MAILBOX": "${user_config.messages_per_mailbox}"
      }
    }
  }
}

Configuration

When installed as a desktop extension, you can configure the following settings through the Claude Desktop UI:

Setting	Description	Default
Enabled Accounts	Comma-separated list of account names to enable	All accounts
Disabled Accounts	Comma-separated list of account names to disable	None
Search Limit	Default number of results for search operations	20
Priority Mailboxes	Comma-separated list of priority mailbox names	INBOX, Sent Messages, Sent, Drafts
JXA Timeout	Timeout for JXA operations (ms)	30000
Max Mailboxes	Maximum mailboxes to check in operations	10
Messages per Mailbox	Messages to check per mailbox	50

Note: If both MAIL_ENABLED_ACCOUNTS and MAIL_DISABLED_ACCOUNTS are specified, only accounts in the enabled list will be active.

Available Tools

`mail_get_accounts`

Get all configured email accounts.

`mail_get_mailboxes`

Get mailbox hierarchy for a specific account.

`mail_get_unread`

Get unread emails (with configurable limit).

`mail_search`

Search emails by text content.

`mail_get_latest`

Get latest emails from a specific account.

`mail_send`

Send email from a specific account.

`mail_mark_read`

Mark emails as read by ID.

`mail_delete`

Delete emails by ID.

Technical Details

JXA Implementation

This implementation uses JavaScript for Automation (JXA) instead of traditional AppleScript, which provides:

Direct JavaScript object returns (no parsing!)
Clean error handling
Type safety with TypeScript
ISO date formats
Proper arrays and nested structures

Example Response

// getAccounts() returns:
[
  {
    name: "Work",
    emailAddresses: ["user@company.com"],
    enabled: true,
    id: "ABC-123-DEF"
  },
  // ...
]

// No string parsing needed!

Development

# Run in development mode
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Create MCPB package
npm run pack

Requirements

macOS (for Apple Mail access)
Node.js 16+ and npm
Apple Mail configured with at least one account

License

MIT

Credits

Clean implementation without string parsing, built with JXA for maximum reliability and performance.