# Mail Mcp

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-dastrobu-mail-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dastrobu](https://agentstack.voostack.com/s/dastrobu)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dastrobu](https://github.com/dastrobu)
- **Source:** https://github.com/dastrobu/mail-mcp

## Install

```sh
agentstack add mcp-dastrobu-mail-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
  - [list_accounts](#list_accounts)
  - [list_mailboxes](#list_mailboxes)
  - [get_message_content](#get_message_content)
  - [get_selected_messages](#get_selected_messages)
  - [find_messages](#find_messages)
  - [list_drafts](#list_drafts)
  - [create_reply_draft](#create_reply_draft)
  - [replace_reply_draft](#replace_reply_draft)
  - [create_outgoing_message](#create_outgoing_message)
  - [list_outgoing_messages](#list_outgoing_messages)
  - [replace_outgoing_message](#replace_outgoing_message)
- [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)

```bash
# 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](https://github.com/dastrobu/mail-mcp/releases):

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

```bash
# 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

```bash
# 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:

```bash
~/go/bin/mail-mcp launchd create
```

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

### Option 4: Build from Source

```bash
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:**

```bash
# 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:

```bash
# 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:**

```bash
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:

```bash
# 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.).

```bash
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):

```json
{
  "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`):

```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`):

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

### Command-Line Options

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

```bash
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`).
4. Select the binary and click **Open**.
5. 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):

```bash
# 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 [DEBUG_LOGGING.md](DEBUG_LOGGING.md) for details.

```bash
mail-mcp --debug
```

### Bash Completion

Enable tab completion for commands and flags:

```bash
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-dastrobu-mail-mcp
- Seller: https://agentstack.voostack.com/s/dastrobu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.