che-apple-mail-mcp

The most comprehensive Apple Mail MCP server - 44 tools with SQLite-powered millisecond search across 250K+ emails.

English | 繁體中文

Why che-apple-mail-mcp?

Quick Start

# Clone and build
git clone https://github.com/kiki830621/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

# Copy to ~/bin and add to Claude Code
# --scope user    : available across all projects (stored in ~/.claude.json)
# --transport stdio: local binary execution via stdin/stdout
# --              : separator between claude options and the command
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

💡 Tip: Always install the binary to a local directory like ~/bin/. Avoid placing it in cloud-synced folders (Dropbox, iCloud, OneDrive) as file sync operations can cause MCP connection timeouts.

Then grant Automation permission in System Settings > Privacy & Security > Automation.

All 42 Tools

Installation

Requirements

• macOS 13.0+
• Xcode Command Line Tools
• Apple Mail with at least one account configured

Step 1: Build

git clone https://github.com/kiki830621/che-apple-mail-mcp.git
cd che-apple-mail-mcp
swift build -c release

Step 2: Configure

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "che-apple-mail-mcp": {
      "command": "/full/path/to/che-apple-mail-mcp/.build/release/CheAppleMailMCP"
    }
  }
}

For Claude Code (CLI)

# Copy to ~/bin and register (user scope = available in all projects)
mkdir -p ~/bin
cp .build/release/CheAppleMailMCP ~/bin/
claude mcp add --scope user --transport stdio che-apple-mail-mcp -- ~/bin/CheAppleMailMCP

Step 3: Grant Permissions

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"

1. Find CheAppleMailMCP and enable permission for Mail.app
2. If using Claude Code, also add Terminal or iTerm

Step 4: Restart Claude

# For Claude Desktop
osascript -e 'quit app "Claude"' && sleep 2 && open -a "Claude"

# For Claude Code - start a new session
claude

Usage Examples

Natural Language (Claude Desktop)

"List all my mail accounts"
"Show unread emails in Gmail inbox"
"Search for emails about 'quarterly report'"
"Send an email to john@example.com about the meeting"
"Flag important emails in red"
"Create a rule to move newsletters to a folder"

Direct Tool Calls (Claude Code)

"Use list_accounts to show my accounts"
"Use search_emails to find emails containing 'invoice'"
"Use set_flag_color to mark email ID 12345 as blue"
"Use check_for_new_mail to refresh"

Flag & Background Colors

Flag Colors (set_flag_color)

Background Colors (set_background_color)

blue, gray, green, none, orange, purple, red, yellow

Troubleshooting

Technical Details

• Framework: MCP Swift SDK v0.10.0
• Automation: AppleScript via NSAppleScript
• Transport: stdio
• Platform: macOS 13.0+ (Ventura and later)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Author

Created by Che Cheng (@kiki830621)

If you find this useful, please consider giving it a star!