Apple Mail MCP

🚀 Apple Mail MCP Server

This is a comprehensive Model Context Protocol (MCP) server that allows AI assistants to access Apple Mail using natural language. Built upon FastMCP, it enables direct operations such as reading, searching, organizing, composing, and managing emails through Claude Desktop or other MCP-compatible clients.

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

🚀 Quick Start

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

Show me an overview of my inbox
How many unread emails do I have?

✨ Features

📧 Email Reading & Search

• Inbox Overview: Dashboard view featuring 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 the 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 an 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/](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 an 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:

1. ✅ Recognize email management requests.
2. ✅ Load expert workflows and best practices.
3. ✅ Use MCP tools intelligently.
4. ✅ 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

💡 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:

1. Download the latest .mcpb file from the Releases page.
2. 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.
3. Grant permissions when prompted:
   • Mail.app Control.
   • Mail Data Access.

Option 2: Manual Installation

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

4. 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"
      ]
    }
  }
}

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

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

📚 Documentation

Available Tools

The MCP server provides 20 tools:

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:

1. Open Claude Desktop settings.
2. Navigate to Developer > MCP Servers.
3. Click on the Apple Mail MCP server.
4. Configure the 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:

1. Mail.app Control: Required to automate Mail operations.
2. 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+.

📄 License

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

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:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. 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

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