Mail MCP

Local MCP server for macOS Mail reads plus visible unsent compose, reply, and forward drafts, and constrained single-message moves.

Built entirely by OpenAI GPT-5.4 via Codex.

Overview

This project exposes Apple Mail accounts, mailboxes, inbox messages, and direct message reads through MCP.

Supported tools:

• mail_check_access
• mail_list_accounts
• mail_list_mailboxes
• mail_list_mailbox_messages
• mail_list_inbox_messages
• mail_get_message
• mail_compose_message
• mail_reply_to_message
• mail_forward_message
• mail_move_message

The primary read workflow is mail_list_inbox_messages, which returns messages for all inboxes and supports headersOnly: true when you only need headers and metadata.

The compose workflow is intentionally narrow: the server can open visible unsent compose, reply, and forward drafts, but it does not expose any send tool. The move workflow is intentionally constrained: it supports moving one message within the same account, but it does not allow moves to Trash or deleted-message mailboxes.

Path Conventions

• Tool inputs use explicit segment arrays:
  • mailboxPathSegments: ["Inbox"]
  • mailboxPathSegments: ["Archive", "2026"]
  • destinationMailboxPathSegments: ["Receipts"]
• Mailbox results include both path and pathSegments. Use path for display and pathSegments when calling tools.
• Message results include both mailboxPath and mailboxPathSegments. Use mailboxPath for display and mailboxPathSegments when calling tools.
• Message results use id. Tools that operate on a specific message require that same value under the input name messageId.

Example round trip:

1. Call mail_list_mailboxes and pick a mailbox result such as:

   {
     "accountId": "account-1",
     "name": "Receipts",
     "path": "Archive / 2026 / Receipts",
     "pathSegments": ["Archive", "2026", "Receipts"]
   }
   

2. Call mail_list_mailbox_messages with:

   {
     "accountId": "account-1",
     "mailboxPathSegments": ["Archive", "2026", "Receipts"]
   }
   

3. Take a returned message object such as:

   {
     "id": 4812,
     "accountId": "account-1",
     "mailboxPath": "Archive / 2026 / Receipts",
     "mailboxPathSegments": ["Archive", "2026", "Receipts"]
   }
   

4. Call mail_get_message with:

   {
     "accountId": "account-1",
     "mailboxPathSegments": ["Archive", "2026", "Receipts"],
     "messageId": 4812
   }
   

Requirements

• Node.js 20+
• macOS
• Mail.app configured with at least one account
• Automation permission to control Mail
• A signed MailMCPHelperApp build

Setup

1. Install dependencies:

   npm install
   

2. Copy .env.example to .env if you want to override defaults:

   cp .env.example .env
   

3. Build the helper app:

   npm run build:helper-app
   

   The build script compiles the app unsigned, then signs the finished bundle with the first local Apple Development identity. Override that selection with MAIL_MCP_CODESIGN_IDENTITY if needed.

4. Run local quality checks:

   npm run verify
   

5. Run a real Mail smoke test:

   npm run test:live
   

Optional environment variables:

• MAIL_MCP_REQUEST_TIMEOUT_MS
• MAIL_MCP_HELPER_TIMEOUT_MS
• MAIL_MCP_HELPER_APP_PATH

Run

Start the server in development:

npm run dev

Build production output:

npm run build
npm start

Permissions

The server launches a signed MailMCPHelperApp and runs Mail automation inside that app process. This keeps the macOS Automation/TCC boundary attached to the helper app instead of Terminal or the client process.

Run mail_check_access once after installation. On first use, macOS may prompt for permission to control Mail.

If the prompt does not appear automatically in your client, launch the helper app directly once:

open MailMCPHelperApp/build/Build/Products/Release/MailMCPHelperApp.app

The server starts even before access is granted. Use mail_check_access to confirm permission state and get an actionable error message if macOS Automation consent is still pending.

To re-run the consent flow on a test machine, reset Mail Apple Events permission for the helper app and then run mail_check_access again:

tccutil reset AppleEvents com.andrewfinke.mailmcphelper

After the reset, confirm that the macOS prompt names MailMCPHelperApp, then confirm System Settings shows MailMCPHelperApp -> Mail.

Verify

npm run verify

Notes

• The filesystem-backed ~/Library/Mail approach is intentionally not used here because it requires broader privacy access and depends on undocumented Mail storage details.
• Message bodies are returned for inbox and mailbox listing tools unless headersOnly: true is set.
• Compose, reply, and forward tools always open visible drafts. Hidden draft mode is intentionally avoided because Mail does not clean up invisible compose objects reliably through automation.
• Raw headers are optional for list tools and default to false.
• Attachment metadata is included, but not attachment bytes.
• The helper app executes JavaScript for Automation in-process via OSAKit.

MCP Setup

The server runs over stdio.

Example client configuration for the built server:

{
  "mcpServers": {
    "mail": {
      "command": "node",
      "args": ["/absolute/path/to/mail-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/mail-mcp",
      "env": {
        "MAIL_MCP_HELPER_APP_PATH": "/absolute/path/to/mail-mcp/MailMCPHelperApp/build/Build/Products/Release/MailMCPHelperApp.app"
      }
    }
  }
}

For local development without building first:

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/mail-mcp"
    }
  }
}