MCP Apple Mail Desktop Extension

You can use the MCP Apple Mail Desktop Extension to connect Apple Mail with Claude via the Model Context Protocol (MCP). It lets you read, search, send, and manage emails directly from Claude, with native JavaScript objects returned through JXA and TypeScript support for strong typing.

How to use

Install and run the MCP server in your environment, then connect it to your MCP client. You can perform actions such as retrieving accounts, listing mailboxes, reading and searching emails, sending from a chosen account, and marking or deleting messages by their IDs. All operations respect account configurations and mailbox hierarchies for seamless workflow.

How to install

Prerequisites: macOS, Node.js 16+ and npm, and Apple Mail configured with at least one account.

Option A — Desktop Extension (Recommended) Download and install the extension package, then configure preferences in Claude Desktop.

Option B — Manual Installation for development or custom setups. Run the following commands to clone, install, build, and pack the MCP extension.

# 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

Configuration

When installing via the manual method, configure the MCP server in Claude Desktop by supplying the runtime command, arguments, and environment variables.

{
  "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}"
      }
    }
  }
}

Notes on configuration and defaults

You can adjust per-login preferences via Claude Desktop UI. If both MAIL_ENABLED_ACCOUNTS and MAIL_DISABLED_ACCOUNTS are provided, only accounts in the enabled list will be active.

Enabled Accounts: comma-separated list of account names to enable
Disabled Accounts: comma-separated list of account names to disable
Search Limit: default number of results for search operations
Priority Mailboxes: comma-separated list of priority mailbox names
JXA Timeout: timeout for JXA operations (ms)
Max Mailboxes: maximum mailboxes to check in operations
Messages per Mailbox: messages to check per mailbox

Available tools and capabilities

Use these tools to interact with your mail data from an MCP client. Each tool operates on authenticated accounts and their mailboxes.

Security and maintenance notes

Keep your environment secure by restricting access to your MCP runtime and by using per-account sending. Ensure macOS and Apple Mail are up to date to maintain compatibility with JXA-based operations.

Development and testing

During development, run in development mode, run tests, build for production, and create the MCPB package as shown.

# Run in development mode
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Create MCPB package
npm run pack

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.