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.

Related MCP server: io.github.p-w-4-z/inbox-mcp

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:

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

Tools (38)

Reading & Search

Organization

Composition

Attachments

Analytics & Export

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:

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

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