Apple Mail

You can run an MCP server that gives AI assistants full access to Apple Mail, enabling reading, searching, composing, organizing, and analyzing emails through natural language. This practical server is built to work with FastMCP and integrates with Claude Desktop for streamlined interactions with your Mail.app workflow.

How to use

To use this MCP server, run it as a local process and connect your MCP client (such as Claude Desktop) to the provided command and arguments. You can perform tasks like listing inbox emails, searching across accounts, composing messages, moving emails between folders, and retrieving analytics and export options. Follow the installation steps to start the server, then configure your MCP client to point to the local Python process that runs the Apple Mail MCP script.

How to install

# Quick Start
# Prerequisites: macOS with Apple Mail configured, Python 3.7+

# 1) Clone the repository
git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp

# 2) Create and activate a virtual environment
python3 -m venv venv && source venv/bin/activate

# 3) Install dependencies
pip install -r requirements.txt

# Optional: build a bundle for Claude Desktop if desired
# An .mcpb bundle is available on the Releases page for one-click install in Claude Desktop.

# Configure the MCP server for Claude Desktop
# This JSON config is placed in Claude Desktop's MCP server settings
{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/apple-mail-mcp/venv/bin/python3",
      "args": ["/path/to/apple-mail-mcp/apple_mail_mcp.py"]
    }
  }
}

Restart Claude Desktop and grant Mail.app permissions when prompted.

## Additional sections

Configuration, safety, and troubleshooting details follow to help you tailor the server to your environment and keep it running smoothly.

## Configuration

User preferences let you tailor the assistant’s context to your workflow. You can provide a JSON configuration that hints at which accounts to emphasize, how many emails to show, and which folders to prioritize.

## Safety and troubleshooting

Safety limits are in place for batch operations to prevent accidental bulk actions. If you need to perform larger actions, adjust the function parameters accordingly. If Mail.app is unresponsive or searches are slow, verify that Mail.app has Automation permissions and tailor search options to balance content retrieval with performance.

## Project structure and notes

The project includes the main MCP server script, dependencies, an MCP Bundle build folder, an optional Email Management Skill, changelog, license, and contributing guidelines.

## License and links

This project is released under the MIT license. You will find related references to FastMCP and the Model Context Protocol for integration details.

## Available tools

### get\_inbox\_overview

Dashboard with unread counts, folders, and recent emails

### list\_inbox\_emails

List emails with account/read-status filtering

### get\_email\_with\_content

Search emails with full content preview

### get\_unread\_count

Unread count per account

### list\_accounts

List all configured Mail accounts

### get\_recent\_emails

Recent emails from a specific account

### get\_recent\_from\_sender

Recent emails from a sender with time-range filters

### search\_emails

Advanced multi-criteria search (subject, sender, dates, attachments)

### search\_by\_sender

Find all emails from a specific sender

### search\_email\_content

Full-text search in email bodies

### search\_all\_accounts

Cross-account unified search

### get\_newsletters

Detect newsletter and subscription emails

### get\_email\_thread

Conversation thread view

### list\_mailboxes

Folder hierarchy with message counts

### move\_email

Move emails between folders (supports nested paths)

### update\_email\_status

Batch mark read/unread, flag/unflag

### manage\_trash

Soft delete, permanent delete, empty trash

### compose\_email

Send new emails (TO, CC, BCC)

### reply\_to\_email

Reply or reply-all with optional CC/BCC

### forward\_email

Forward with optional message, CC/BCC

### manage\_drafts

Create, list, send, and delete drafts

### list\_email\_attachments

List attachments with names and sizes

### save\_email\_attachment

Save attachments to disk

### get\_statistics

Email analytics (volume, top senders, read ratios)

### export\_emails

Export single emails or mailboxes to TXT/HTML

### inbox\_dashboard

Interactive UI dashboard (requires mcp-ui-server)