Mail Mcp

Mail MCP Server

[](https://github.com/dastrobu/mail-mcp/actions/workflows/ci.yaml)

A Model Context Protocol (MCP) server providing programmatic access to macOS Mail.app using JavaScript for Automation (JXA).

Table of Contents

• [Overview](#overview)
• [Security & Privacy](#security--privacy)
• [Features](#features)
• [Requirements](#requirements)
• [Installation](#installation)
• [Option 1: Homebrew (Recommended)](#option-1-homebrew-recommended)
• [Option 2: Download Binary](#option-2-download-binary)
• [Option 3: Install via Go](#option-3-install-via-go)
• [Option 4: Build from Source](#option-4-build-from-source)
• [Usage](#usage)
• [HTTP Transport (Recommended)](#http-transport-recommended)
• [STDIO Transport](#stdio-transport)
• [MCP Client Configuration](#mcp-client-configuration)
• [Command-Line Options](#command-line-options)
• [Permissions](#permissions)
• [Accessibility Permissions](#accessibility-permissions)
• [Automation Permissions](#automation-permissions)
• [Manual Permission Configuration](#manual-permission-configuration)
• [Resetting Permissions](#resetting-permissions)
• [Troubleshooting](#troubleshooting)
• [Automation Permission Errors](#automation-permission-errors)
• [Mail.app Not Running](#mailapp-not-running)
• [Debug Mode](#debug-mode)
• [Bash Completion](#bash-completion)
• [Available Tools](#available-tools)
• [listaccounts](#listaccounts)
• [listmailboxes](#listmailboxes)
• [getmessagecontent](#getmessagecontent)
• [getselectedmessages](#getselectedmessages)
• [findmessages](#findmessages)
• [listdrafts](#listdrafts)
• [createreplydraft](#createreplydraft)
• [replacereplydraft](#replacereplydraft)
• [createoutgoingmessage](#createoutgoingmessage)
• [listoutgoingmessages](#listoutgoingmessages)
• [replaceoutgoingmessage](#replaceoutgoingmessage)
• [Upgrading](#upgrading)
• [Homebrew](#homebrew)
• [Manual Installation](#manual-installation)
• [Uninstalling](#uninstalling)
• [Homebrew](#homebrew-1)
• [Manual Installation](#manual-installation-1)
• [Architecture](#architecture)
• [Development](#development)
• [Build](#build)
• [Git Hooks](#git-hooks)
• [Format](#format)
• [Update Table of Contents](#update-table-of-contents)
• [Clean](#clean)
• [Error Handling](#error-handling)
• [Limitations](#limitations)
• [Rich Text Limitations](#rich-text-limitations)
• [License](#license)

Overview

This MCP server enables AI assistants and other MCP clients to interact with Apple Mail on macOS. It provides read-only access to mailboxes, messages, and search functionality through a clean, typed interface.

Security & Privacy

• Human-in-the-loop design: No emails are sent automatically - all drafts require manual sending. This prevents agents from sending emails without human oversight.
• No data transmitted outside of the MCP connection
• Runs locally on your machine
• Grant automation and accessibility permissions to the MCP server alone, not to the terminal or any other application like Claude Code.
• No credentials to a mail account ot SMTP server required, all interactions happen transparently with the Mail.app.

Features

• List Accounts: Enumerate all configured email accounts with their properties
• List Mailboxes: Enumerate all available mailboxes and accounts
• Get Message Content: Fetch detailed content of individual messages
• Get Selected Messages: Retrieve currently selected message(s) in Mail.app
• Find Messages: Search messages with efficient filtering by subject, sender, read status, flags, and date ranges
• Create Reply Draft: Create a reply to a message with preserved quotes using the Accessibility API.
• Create Outgoing Message: Create new email drafts with Markdown rendering to rich text.
• Replace Drafts: Robustly update existing drafts (replies or standalone) while preserving quotes and signatures.
• Rich Text Support: Native support for Markdown (headings, bold, italic, links, strikethrough, lists, code blocks, and more) using native Mail.app rendering via the Accessibility API.

Requirements

• macOS (Mail.app is macOS-only)
• Mail.app configured with at least one email account (does not need to be running at server startup)
• Automation and Accessibility permissions for Mail.app (see [Permissions](#permissions) below)

Installation

Option 1: Homebrew (Recommended)

# Add the tap
brew tap dastrobu/tap

# Install
brew install mail-mcp

# Start the service (Standard)
brew services start mail-mcp

# OR use the built-in subcommand for more customization (port, debug)
mail-mcp launchd create

Important: For proper automation permissions, you must run the server as a service (not from Terminal). Using brew services start is the standard way, while mail-mcp launchd create offers more customization.

Note: When you upgrade via brew upgrade mail-mcp, the launchd service will automatically restart with the new version if it's already running. You don't need to manually recreate the service.

➡️ See [Usage](#usage) for how to configure and use the server.

Option 2: Download Binary

Download the latest release from GitHub Releases:

• Intel Mac: mail-mcp_*_darwin_amd64.tar.gz
• Apple Silicon: mail-mcp_*_darwin_arm64.tar.gz

# Extract
tar -xzf mail-mcp_*.tar.gz

# Set up launchd service (uses full path to binary)
mail-mcp launchd create

➡️ See [Usage](#usage) for how to configure and use the server.

Option 3: Install via Go

# Install directly from GitHub (requires Go 1.26+)
go install github.com/dastrobu/mail-mcp@latest

# Set up launchd service
mail-mcp launchd create

Note: Ensure $GOPATH/bin (or $HOME/go/bin) is in your PATH, or use the full path:

~/go/bin/mail-mcp launchd create

➡️ See [Usage](#usage) for how to configure and use the server.

Option 4: Build from Source

git clone https://github.com/dastrobu/mail-mcp.git
cd mail-mcp

# Build locally
go build -v -o mail-mcp .

# Set up launchd service
./mail-mcp launchd create

➡️ See [Usage](#usage) for how to configure and use the server.

Usage

The server supports two transport modes: HTTP (recommended) and STDIO.

HTTP Transport (Recommended)

HTTP mode runs the server as a standalone daemon, allowing automation permissions to be granted directly to the mail-mcp binary rather than the parent application.

⚠️ To get permissions granted to the binary (not Terminal or IDE), you must launch it without Terminal as the parent process.

Option 1: Using launchd (Recommended for Production)

Create a launch agent to run the server in the background.

Quick setup using the built-in subcommand:

# Run the setup subcommand
mail-mcp launchd create

➡️ See [MCP Client Configuration](#mcp-client-configuration) to connect your MCP client.

Or alternatively, create the launch agent manually:

# See available options
mail-mcp launchd create -h

# With custom port
mail-mcp --port=3000 launchd create

# With debug logging enabled
mail-mcp --debug launchd create

# Disable automatic startup on login (start manually instead)
mail-mcp launchd create --disable-run-at-load

# The subcommand will:
# - Create the launchd plist
# - Load and start the service
# - Show you the connection URL and useful commands

To remove the service:

mail-mcp launchd remove

Check logs: tail -f ~/Library/Logs/com.github.dastrobu.mail-mcp/mail-mcp.log ~/Library/Logs/com.github.dastrobu.mail-mcp/mail-mcp.err

To stop: launchctl stop com.github.dastrobu.mail-mcp To unload: launchctl unload ~/Library/LaunchAgents/com.github.dastrobu.mail-mcp.plist

Option 2: Running from Terminal (Quick Testing)

If you launch from Terminal, Terminal will be asked for permissions, not the binary:

# This will prompt for Terminal's permissions (not ideal)
mail-mcp --transport=http

# Custom port
mail-mcp --transport=http --port=3000

# Custom host and port
mail-mcp --transport=http --host=0.0.0.0 --port=3000

This is fine for quick testing, but for production use launchd.

Connect MCP clients to: http://localhost:8787

➡️ See [MCP Client Configuration](#mcp-client-configuration) to connect your MCP client.

STDIO Transport

STDIO mode runs the server as a child process of the MCP client. Note that automation permissions will be required for the parent application (Terminal, Claude Desktop, etc.).

mail-mcp

➡️ See [MCP Client Configuration](#mcp-client-configuration) to connect your MCP client.

MCP Client Configuration

VS Code Configuration

Make sure the server is running, see [HTTP Transport](#http-transport-recommended)

Configure VS Code (~/Library/Application Support/Code/User/mcp.json on macOS):

{
  "servers": {
    "mail-mcp": {
      "type": "http",
      "url": "http://localhost:8787"
    }
  }
}

Zed Configuration

Make sure the server is running, see [HTTP Transport](#http-transport-recommended)

Configure Zed (~/.config/zed/settings.json):

{
  "context_servers": {
    "mail-mcp": {
      "url": "http://localhost:8787"
    }
  }
}

Claude Desktop Configuration

Make sure the server is running, see [HTTP Transport](#http-transport-recommended)

Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mail-mcp": {
      "url": "http://localhost:8787"
    }
  }
}

Command-Line Options

Use -h or --help with any command to see available options:

mail-mcp -h                    # Show main help
mail-mcp launchd -h            # Show launchd subcommands
mail-mcp launchd create -h     # Show launchd create options

Available options:

--transport=[stdio|http]  Transport type (default: stdio)
--port=PORT              HTTP port (default: 8787, only used with --transport=http)
--host=HOST              HTTP host (default: localhost, only used with --transport=http)
--debug                  Enable debug logging of tool calls and results to stderr

-h, --help               Show help message

Commands:
  launchd create         Set up launchd service for automatic startup (HTTP mode)
                         Use --debug flag to enable debug logging in the service
                         Use --disable-run-at-load to prevent automatic startup on login
  launchd remove         Remove launchd service
  completion bash        Generate bash completion script

Options can also be set via environment variables:

APPLE_MAIL_MCP_TRANSPORT=http
APPLE_MAIL_MCP_PORT=8787
APPLE_MAIL_MCP_HOST=localhost
APPLE_MAIL_MCP_DEBUG=true
APPLE_MAIL_MCP_RICH_TEXT_STYLES=/path/to/custom_styles.yaml

➡️ See [MCP Client Configuration](#mcp-client-configuration) to connect your MCP client.

Permissions

macOS requires both Automation and Accessibility permissions for full functionality.

Accessibility Permissions

The draft creation and replacement tools (create_reply_draft, replace_reply_draft, create_outgoing_message, replace_outgoing_message) use the macOS Accessibility API to simulate pasting content. This is the only reliable way to support rich text (Markdown) while preserving original message quotes and signatures. If you only want to use tools that read emails, you can skip granting the accessibility permission.

To ensure the highest level of security, grant accessibility permissions directly to the mail-mcp binary alone:

1. Open System Settings → Privacy & Security → Accessibility.
2. Click the + (plus) button at the bottom of the list.
3. In the file picker that appears, navigate to the path where mail-mcp is installed.

• Tip: Press Cmd + Shift + G to enter the path manually (e.g. /usr/local/bin/mail-mcp).

1. Select the binary and click Open.
2. Ensure the toggle switch next to mail-mcp is ON.

If permissions are missing, these tools will return an error explaining what to do.

Automation Permissions

macOS requires automation permissions to control Mail.app. The permission behavior depends on which transport mode you use:

HTTP Transport (Recommended)

When using --transport=http, permissions can be granted to the mail-mcp binary itself, but only if launched without Terminal as the parent process.

Using launchd (recommended):

1. Set up the launchd service: mail-mcp launchd create
2. macOS will prompt for automation permissions for mail-mcp binary
3. Click OK to grant access
4. The server is now ready to use

Using Finder:

1. Double-click the mail-mcp binary in Finder
2. macOS will prompt for automation permissions for mail-mcp binary
3. Click OK to grant access

Using Terminal (quick testing only):

1. Run mail-mcp --transport=http from Terminal
2. macOS will prompt for automation permissions for Terminal.app (not the binary)
3. Click OK to grant access to Terminal
4. Note: This grants permission to Terminal, not the binary

Advantage: With launchd or Finder launch, permissions stay with the binary and work with all MCP clients. With Terminal launch, only Terminal gets permissions.

STDIO Transport

When using STDIO mode (default), permissions are granted to the parent process (Terminal, Claude Desktop, etc.) that launches the server:

1. Start the server (or let your MCP client start it)
2. macOS will prompt for automation permissions on first run
3. Click OK to grant access to the parent application
4. The server is now ready to use

Note: If you switch between different applications (e.g., Terminal vs Claude Desktop), each will need its own automation permission.

Manual Permission Configuration

If the prompt doesn't appear or you need to change permissions:

1. Open System Settings → Privacy & Security → Automation
2. Find mail-mcp (HTTP mode) or the parent application (STDIO mode)
3. Enable the checkbox next to Mail
4. Restart the server

Resetting Permissions

To reset automation permissions (useful for testing or troubleshooting):

# Reset all automation permissions (will prompt again on next run)
tccutil reset AppleEvents

# Reset for a specific application (e.g., Terminal)
tccutil reset AppleEvents com.apple.Terminal

# Reset for a specific application (e.g., Mail)
tccutil reset Accessibility

After resetting, the next time the server tries to control Mail.app, macOS will show the permission prompt again.

Troubleshooting

Automation Permission Errors

If you see:

Mail.app startup check failed: osascript execution failed: signal: killed

Solution: Grant automation permissions using the steps in [Automation Permissions](#automation-permissions) above.

Mail.app Not Running

The server can start without Mail.app running. When you try to use a tool and Mail.app is not running, you'll receive a clear error message:

• "Mail.app is not running. Please start Mail.app and try again" - Simply open Mail.app and retry
• "Mail.app automation permission denied..." - Grant automation permissions in System Settings > Privacy & Security > Automation

Tool calls will automatically work once Mail.app is started and permissions are granted.

Debug Mode

When --debug is enabled, the server logs all MCP protocol interactions and JXA script diagnostics to stderr, including tool calls, results, and JXA script logs. See [DEBUGLOGGING.md](DEBUGLOGGING.md) for details.

mail-mcp --debug

Bash Completion

Enable tab completion for commands and flags:

# Generate completion script
mail-mcp completion bash > /usr/local/etc/bash_completion.d/mail-mcp

# Or add to your ~/.bashrc or ~/.bash_profile
source     # Completes: http, stdio
mail-mcp launchd         # Complet

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dastrobu](https://github.com/dastrobu)
- **Source:** [dastrobu/mail-mcp](https://github.com/dastrobu/mail-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.