Apple Mail MCP Server wires a Python-based MCP server into Claude Desktop (or compatible MCP clients) to expose Apple Mail functionality via natural language prompts. It provides a suite of tools for reading, searching, composing, organizing, and analyzing emails, including inbox overviews, multi-criteria search, mailbox management, and email analytics. The server is built on FastMCP and ships with a rich set of 26 tools across Reading & Search, Organization, Composition, Attachments, and Analytics & Export, enabling conversational access to your Mail data and workflows. To use it, run the MCP server in your environment and point your MCP client to the server's address/port. You can then invoke specific tools (for example get_inbox_overview, search_emails, compose_email, move_email, or get_statistics) to perform actions or extract information from your Apple Mail accounts. If you use Claude Desktop, you’ll configure the MCP server in Claude’s MCP Servers settings as shown in the README examples, providing the Python path to the server script and the working directory. The server supports environment-driven customization (for example USER_EMAIL_PREFERENCES) to tailor the assistant’s behavior to your workflow.

Prerequisites:

• macOS with Apple Mail configured
• Python 3.7+
• Internet access to install dependencies

Installation steps:

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 (recommended): python3 -m venv venv source venv/bin/activate
3. Install Python dependencies: pip install -r requirements.txt
4. Run the MCP server directly (local testing): python3 apple_mail_mcp.py

   or using a virtualenv Python path as configured in your MCP client

5. Configure Claude Desktop or your MCP client to point to the server:
   • If using Claude Desktop, add a MCP Server entry with: command: /path/to/venv/bin/python3 args: [ /path/to/apple-mail-mcp/apple_mail_mcp.py ]
6. Optional: set environment variables to customize behavior (see additional notes):
   • USER_EMAIL_PREFERENCES for preferred folders, limits, etc.

Notes:

• The server relies on macOS Mail access permissions; ensure necessary Automation and Mail Data Access permissions are granted in System Settings.
• If you modify tool usage or want to limit actions, adjust parameters passed to the tools via the MCP client.

Tips and common issues:

• Ensure Mail.app Automation permissions are granted when first running the server; without this, some tools will fail to access mail data.
• If searches seem slow, consider adjusting include_content or max_results in your queries (as recommended in the README).
• For CLI or integration testing, you can run the server from a virtual environment to isolate dependencies.
• If you prefer a one-click install for Claude Desktop, check the Releases page for an MCP bundle (.mcpb).
• The tools cover a wide range of email management tasks; consult the Tools table in the README to discover exact tool capabilities and parameters.