mail-mcp

MCP server that gives Claude (and other MCP hosts) full access to Mail.app on macOS — search, read, send, reply, flag, move, and more — across every account configured in Mail.app (iCloud, Exchange, IMAP, etc.).

Prerequisites

• macOS (Mail.app required)

• Node.js 20+

• An MCP host: Claude Desktop, Amazon Quick, or any stdio MCP client

Installation

Claude Desktop — one-click install (recommended)

1. Download mail-mcp.dxt from the latest release

2. Double-click the .dxt file — Claude Desktop installs it automatically

3. Grant the required macOS permissions (see below)

Manual / Amazon Quick / other hosts

npx @p-l-ta/mail-mcp

Or install globally:

npm install -g @p-l-ta/mail-mcp
mail-mcp

Point your MCP host at the mail-mcp binary (stdio transport). Example config:

{
  "mcpServers": {
    "mail-app": {
      "command": "npx",
      "args": ["@p-l-ta/mail-mcp"]
    }
  }
}

Required macOS permissions

Grant these to the application that runs the MCP host (Claude Desktop, Amazon Quick, etc.):

The MCP server process inherits permissions from the host application that launches it.

Tools

How it works

• Search & read — queries Mail's own Envelope Index SQLite database directly for fast, structured results across all accounts

• Actions (send, reply, flag, move, trash) — driven by AppleScript automation against Mail.app, so they work even for accounts where messages aren't stored as local files

Development

npm install
npm run dev          # tsx watch — live reload
npm test             # vitest unit tests
npm run build        # compile TypeScript → dist/
npm run dxt          # build Claude Desktop extension → build/mail-mcp.dxt

Interactive MCP testing:

npm run build
npx @modelcontextprotocol/inspector node dist/server.js

License

ISC