Apple Mail MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with natural language access to Apple Mail. Built with FastMCP, this server enables reading, searching, organizing, composing, and managing emails directly through Claude Desktop or other MCP-compatible clients.

✨ NEW: Now includes the Email Management Expert Skill - a comprehensive Claude Code skill that teaches Claude intelligent email management workflows and productivity strategies!

Features

📧 Email Reading & Search

Inbox Overview: Dashboard view with unread counts, folder structure, and recent emails
Advanced Search: Multi-criteria search (subject, sender, attachments, read status, date ranges)
Cross-Folder Search: Search across all mailboxes or specific folders
Email Content: Full content preview with configurable length
Thread View: Conversation threading across all mailboxes
Recent Emails: Quick access to latest messages per account

📁 Email Organization

Mailbox Management: List and navigate folder hierarchies
Move Emails: Transfer messages between folders (supports nested mailboxes)
Status Updates: Batch mark as read/unread, flag/unflag
Trash Management: Soft delete, permanent delete, and empty trash

✉️ Email Composition

Compose: Send new emails with TO, CC, BCC support
Reply: Respond to messages (single or reply-all)
Forward: Forward emails with optional custom message
Draft Management: Create, list, send, and delete drafts

📎 Attachment Handling

List Attachments: View all attachments with names and sizes
Save Attachments: Download specific attachments to disk

📊 Analytics & Export

Statistics: Comprehensive email analytics (volume, top senders, mailbox distribution)
Export: Export single emails or entire mailboxes to TXT/HTML formats

🎓 Email Management Expert Skill

NEW: This repository now includes a comprehensive Claude Code Skill that teaches Claude how to be an expert email management assistant!

What's a Skill?

A Skill is a Claude Code feature that packages expertise and workflows, teaching Claude not just what it can do (MCP tools), but how to do it effectively. It's like giving Claude a productivity consultant for email management.

MCP + Skill = Intelligent Email Management

Apple Mail MCP (this server) = The tools (18 email functions)
Email Management Skill (skill-email-management/) = The expertise (workflows, strategies, best practices)

Together, they create an intelligent assistant that knows both the capabilities and the best ways to use them.

What You Get with the Skill

📋 Complete Workflows:

Inbox Zero - Achieve and maintain empty inbox
Daily Email Triage - Process emails quickly (10-15 min)
Folder Organization - Structure strategies and filing systems
Advanced Search - Find any email instantly
Bulk Operations - Clean up and organize efficiently

🧠 Expert Knowledge:

Industry-standard productivity methods (GTD, Inbox Zero)
Tool orchestration patterns (when to use which tool)
Safety-first approaches (backups, limits, confirmations)
Context-aware suggestions based on inbox state

📚 Ready-to-Use Resources:

6 detailed documents (3,500+ lines)
Copy-paste workflow templates
Comprehensive search pattern reference
Common scenarios and solutions

Installing the Skill

The skill works alongside the MCP. Install it to your Claude Code user scope:

# Clone this repo (if you haven't already)
git clone https://github.com/patrickfreyer/apple-mail-mcp.git
cd apple-mail-mcp

# Install skill to user scope (available in all projects)
cp -r skill-email-management ~/.claude/skills/email-management

That's it! The skill activates automatically when you mention email management topics.

Using the Skill

Once installed, just ask Claude Code about email management:

Examples:

"Help me achieve inbox zero"
"Triage my inbox"
"How should I organize my project emails?"
"Find all emails from John about the Alpha project"
"Clean up old emails from last year"

Claude will now:

✅ Recognize email management requests
✅ Load expert workflows and best practices
✅ Use MCP tools intelligently
✅ Provide actionable step-by-step guidance

What's Inside the Skill

skill-email-management/
├── SKILL.md                        # Core workflows & tool orchestration
├── examples/
│   ├── inbox-zero-workflow.md     # Complete inbox zero methodology
│   ├── email-triage.md            # Quick daily triage techniques
│   └── folder-organization.md     # Folder structure strategies
└── templates/
    ├── common-workflows.md        # Copy-paste workflow patterns
    └── search-patterns.md         # Comprehensive search reference

📖 Read the full Skill documentation →

Before vs. After the Skill

| Before Skill | After Skill | |--------------|-------------| | "Show me my emails" | "Let me analyze your inbox state and suggest an optimal workflow" | | Uses tools individually | Orchestrates multi-step workflows intelligently | | Generic responses | Expert productivity strategies and context-aware advice | | User figures out sequences | Pre-built workflows (Inbox Zero, GTD, triage, etc.) |

💡 Pro Tip: The skill and MCP are designed to work together. Install both for the complete intelligent email management experience!

Installation

Prerequisites

macOS with Apple Mail configured
Python 3.7 or higher
At least one Mail account configured in Apple Mail
Claude Desktop (for MCP Bundle installation) or any MCP-compatible client

Option 1: MCP Bundle (.mcpb) - Recommended

The easiest way to install is using the pre-built MCP Bundle:

Download the latest .mcpb file from the Releases page
Install in Claude Desktop:
- Open Claude Desktop settings
- Navigate to Developer > MCP Servers
- Click Install from file
- Select the downloaded .mcpb file
- Restart Claude Desktop
Grant permissions when prompted:
- Mail.app Control
- Mail Data Access

Option 2: Manual Installation

Clone the repository:

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

Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Configure Claude Desktop by adding to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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

Building Your Own .mcpb Bundle

To build a distributable MCP Bundle:

cd apple-mail-mcpb
./build-mcpb.sh

The script will create apple-mail-mcp-v{version}.mcpb in the parent directory.

Usage Examples

Once installed, you can interact with Apple Mail using natural language in Claude:

Reading Emails

Show me an overview of my inbox
How many unread emails do I have?
List recent emails from my work account
Search for emails about "project update" in my Gmail account
Search for emails about "invoice" across all folders in my work account
Show me the conversation thread about "meeting"

Organizing Emails

Move emails with "invoice" in the subject to my Archive folder
Mark all emails from john@example.com as read
Flag important emails about "deadline"
Delete emails from newsletter@example.com

Composing & Responding

Reply to the email about "Domain name" with "Thanks for the update!"
Compose an email to jane@example.com from my work account
Forward the email about "meeting notes" to team@example.com
Create a draft email to John about project status

Managing Attachments

List attachments in emails about "invoice"
Save the PDF attachment from the email about "contract"

Analytics & Export

Show me email statistics for the last 30 days
Export all emails from my Archive folder to HTML
Get statistics for emails from sarah@example.com

Available Tools

The MCP server provides 20 tools:

| Tool | Description | |------|-------------| | get_inbox_overview | Comprehensive dashboard with unread counts, folders, and recent emails | | list_inbox_emails | List emails from inbox with filtering options | | get_email_with_content | Search emails with full content preview | | search_emails | Advanced search with multiple criteria | | get_unread_count | Quick unread count per account | | list_accounts | List all configured Mail accounts | | get_recent_emails | Recent emails from specific account | | list_mailboxes | List folder structure with message counts | | move_email | Move emails between folders | | reply_to_email | Reply to messages | | compose_email | Send new emails | | forward_email | Forward messages | | update_email_status | Mark read/unread, flag/unflag | | manage_trash | Delete operations (soft/hard delete, empty trash) | | get_email_thread | View conversation threads | | manage_drafts | Draft lifecycle management | | list_email_attachments | List attachments | | save_email_attachment | Download attachments | | get_statistics | Email analytics | | export_emails | Export to TXT/HTML |

Configuration

Email Preferences (Optional)

You can configure personal email preferences that will be provided to the AI assistant when using email tools. This helps Claude understand your preferred email accounts, defaults, and workflow.

MCP Bundle Installation (.mcpb):

When installing via the .mcpb bundle, you can set preferences through Claude Desktop:

Open Claude Desktop settings
Navigate to Developer > MCP Servers
Click on the Apple Mail MCP server
Configure Email Preferences field

Example preferences:

Default to BCG account, show max 50 emails, prefer Archive and Projects folders

Manual Installation:

Add the env section to your claude_desktop_config.json:

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

What to include in preferences:

Default email account name (e.g., "BCG", "Gmail", "Personal")
Preferred maximum email results
Frequently used mailboxes/folders
Any workflow preferences

These preferences are automatically injected into every tool's description, helping Claude make better decisions aligned with your workflow.

Safety Limits

Several operations include safety limits to prevent accidental bulk actions:

update_email_status: Default max 10 updates
manage_trash: Default max 5 deletions
move_email: Default max 1 move

These limits can be adjusted via function parameters when needed.

Permissions

On first use, macOS will prompt for permissions:

Mail.app Control: Required to automate Mail operations
Mail Data Access: Required to read email content

Grant both permissions in System Settings > Privacy & Security > Automation for full functionality.

Technical Details

Framework: FastMCP - Python MCP server framework
Automation: AppleScript for Mail.app interaction
Platform: macOS only (requires Apple Mail)
Python: 3.7+

Project Structure

apple-mail-mcp/
├── apple_mail_mcp.py              # Main MCP server
├── requirements.txt               # Python dependencies
├── README.md                      # This file
├── LICENSE                        # MIT License
├── CHANGELOG.md                   # Version history
├── claude_desktop_config_example.json  # Configuration example
├── apple-mail-mcpb/
│   ├── manifest.json              # MCP Bundle metadata
│   └── build-mcpb.sh             # Bundle build script
└── skill-email-management/        # 🎓 Email Management Expert Skill
    ├── README.md                  # Skill installation & usage guide
    ├── SKILL.md                   # Core workflows & expertise
    ├── examples/                  # Workflow examples
    │   ├── inbox-zero-workflow.md
    │   ├── email-triage.md
    │   └── folder-organization.md
    └── templates/                 # Reusable patterns
        ├── common-workflows.md
        └── search-patterns.md

Troubleshooting

Mail.app Not Responding

Ensure Mail.app is running
Check that permissions are granted in System Settings
Restart Mail.app and Claude Desktop

Slow Performance

Fetching email content is slower than metadata
Use include_content: false when content preview isn't needed
Reduce max_results for large searches

Mailbox Not Found

Use exact folder names as they appear in Mail.app
For nested folders, use "/" separator: "Projects/Amplify Impact"
Some accounts (Exchange) may use different mailbox names

Permission Errors

# Grant permissions via System Settings
System Settings > Privacy & Security > Automation > [Your Terminal/Claude]

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Roadmap

Recent additions:

[x] ✨ Email Management Expert Skill with workflows and best practices (v1.0.0)

Future enhancements under consideration:

[ ] Smart mailbox support
[ ] Rule/filter management
[ ] Email template system
[ ] Bulk operations improvements
[ ] Enhanced search operators
[ ] Multi-account operations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with FastMCP by Jeremiah Lowin
Inspired by the Model Context Protocol specification
Thanks to Anthropic for Claude Desktop, MCP support, and Claude Code Skills
Email Management Expert Skill demonstrates best practices for combining MCPs with Skills

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history and release notes.

Made with ❤️ for the Claude Desktop community