home / mcp / apple mail mcp server

Apple Mail MCP Server

MCP server giving AI assistants full access to Apple Mail - read, search, compose, organize & analyze emails via natural language

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "patrickfreyer-apple-mail-mcp": {
      "command": "/path/to/apple-mail-mcp/venv/bin/python3",
      "args": [
        "/path/to/apple-mail-mcp/apple_mail_mcp.py"
      ],
      "env": {
        "USER_EMAIL_PREFERENCES": "Default to BCG account, show max 50 emails, prefer Archive and Projects folders"
      }
    }
  }
}

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

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