Apple Mail MCP Server

Star History

An MCP server that gives AI assistants full access to Apple Mail -- read, search, compose, organize, and analyze emails via natural language. Built with FastMCP.

Quick Start

Prerequisites: macOS with Apple Mail configured, Python 3.14+, uv

git clone https://github.com/isityael/apple-mail-mcp.git
cd apple-mail-mcp
uv sync

Add to your Claude Desktop config (~/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 and grant Mail.app permissions when prompted.

Tip: An .mcpb bundle is also available on the Releases page for one-click install in Claude Desktop.

Codex Plugin

This repository is also a Codex plugin source. The Codex plugin manifest lives at .codex-plugin/plugin.json, bundles the Email Management skill from skills/, and exposes the Apple Mail MCP server through .mcp.json.

The bundled MCP server is local-only and macOS-specific. It launches start_mcp.sh, which uses the repo-local uv environment and requires Mail.app Automation permissions on the machine running Codex.

Forwarded optional environment variables:

Variable	Purpose
USER_EMAIL_PREFERENCES	Adds user workflow preferences to tool descriptions
APPLE_MAIL_MCP_READ_ONLY	Hides send-capable tools and blocks draft sending

Claude Desktop support remains separate: use the .mcpb bundle or explicit MCP config below.

Tools (38)

Reading & Search

Tool	Description
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, flag color)
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

Organization

Tool	Description
list_mailboxes	Folder hierarchy with message counts
move_email	Move emails between folders (supports nested paths and exact message IDs)
update_email_status	Batch mark read/unread, flag/unflag with optional flag colors
manage_trash	Soft delete, permanent delete, empty trash
synchronize_account	Ask Mail to synchronize one account or all accounts

Composition

Tool	Description
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

Attachments

Tool	Description
list_email_attachments	List attachments with names and sizes
save_email_attachment	Save attachments to disk

Analytics & Export

Tool	Description
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)

Configuration

User Preferences (Optional)

Set the USER_EMAIL_PREFERENCES environment variable to give the assistant context about your workflow:

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

For .mcpb installs, configure this in Claude Desktop under Developer > MCP Servers > Apple Mail MCP.

Read-Only Mode

Use --read-only to disable send-capable tools while keeping inbox, search, organization, and draft-management workflows available. In read-only mode, compose_email, reply_to_email, and forward_email are hidden, and draft sending is blocked.

{
  "mcpServers": {
    "apple-mail": {
      "command": "/path/to/venv/bin/python3",
      "args": ["/path/to/apple_mail_mcp.py", "--read-only"]
    }
  }
}

For .mcpb installs, the same behavior is available through the Read-Only Mode package setting.

HTML Compose

compose_email now supports an optional body_html parameter for rich email formatting. If body_html is omitted, the existing plain-text behavior is unchanged.

Releases

Stable releases are tag-driven. When a tag such as v2.1.2 is pushed, Woodpecker now:

• builds a version-matched .mcpb archive
• generates release notes from commit history
• uploads the bundle, checksum, and notes to the GitHub release
• updates the Homebrew tap after the GitHub release succeeds

Regular pushes to main still run CI and build verification, but they do not publish a stable GitHub release.

Safety Limits

Batch operations have conservative defaults to prevent accidental bulk actions:

Operation	Default Limit
update_email_status	10 emails
manage_trash	5 emails
move_email	1 email

Override via function parameters when needed.

Usage Examples

Show me an overview of my inbox
Search for emails about "project update" in my Gmail
Reply to the email about "Domain name" with "Thanks for the update!"
Draft an HTML email with a bold heading and a link to the project tracker
Move emails with "invoice" in the subject to my Archive folder
Show me email statistics for the last 30 days

Email Management Skill

A companion Email Management skill is included at skills/email-management/ for inbox zero, daily triage, folder organization, flag-color workflows, exact message-id moves, and account synchronization. Codex loads it through the plugin manifest. Claude Code users can install it alongside the MCP manually:

cp -r skills/email-management ~/.claude/skills/email-management

See skills/email-management/SKILL.md for details.

Requirements

• macOS with Apple Mail configured
• Python 3.14+
• fastmcp (+ optional mcp-ui-server for dashboard)
• Claude Desktop or any MCP-compatible client
• Mail.app permissions: Automation + Mail Data Access (grant in System Settings > Privacy & Security > Automation)

Troubleshooting

Issue	Fix
Mail.app not responding	Ensure Mail.app is running; check Automation permissions in System Settings
Slow searches	Set include_content: false and lower max_results
Mailbox not found	Use exact folder names; nested folders use / separator (e.g., Projects/Alpha)
Permission errors	Grant access in System Settings > Privacy & Security > Automation

Project Structure

apple-mail-mcp/
├── apple_mail_mcp.py          # Script entrypoint
├── start_mcp.sh               # Bundle/runtime launcher
├── pyproject.toml             # Python project metadata
├── uv.lock                    # Locked dependencies
├── apple_mail_mcp/            # MCP package and tool modules
├── apple-mail-mcpb/           # MCP Bundle build files
├── .codex-plugin/             # Codex plugin manifest
├── .mcp.json                  # Codex-bundled MCP server config
├── skills/email-management/   # Email Management Expert Skill
├── CHANGELOG.md
├── LICENSE
└── README.md

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit and push
4. Open a Pull Request

License

MIT -- see LICENSE.

Links

• Changelog
• Issues
• Discussions
• FastMCP
• Model Context Protocol