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)

1. Download the apple-mail.mcpb extension package
2. Double-click to install in Claude Desktop
3. 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.