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?

Feature	Other MCPs	che-apple-mail-mcp
Total Tools	~20	44
Language	Python	Swift (Native)
Search Speed	Seconds (AppleScript)	Milliseconds (SQLite)
Search Fields	Subject/Sender	Subject/Sender/Recipient/Date
Batch Operations	No	Up to 50 emails per call
Mailbox Management	Basic	Full CRUD
Email Colors	No	7 flag colors + background
VIP Management	No	Yes
Rule Management	Partial	Full CRUD
Signatures	No	Yes
Raw Headers/Source	No	Yes

---

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

Accounts (2)

Tool	Description
list_accounts	List all mail accounts
get_account_info	Get account details

Mailboxes (4)

Tool	Description
list_mailboxes	List all mailboxes (folders)
create_mailbox	Create a new mailbox
delete_mailbox	Delete a mailbox
get_special_mailboxes	Get special mailbox names (inbox, drafts, sent, trash, junk, outbox)

Emails (7)

Tool	Description
list_emails	List emails in a mailbox
get_email	Get full email content
search_emails	Search by subject/content
get_unread_count	Get unread count
get_email_headers	Get all email headers
get_email_source	Get raw email source
get_email_metadata	Get metadata (forwarded, replied, size)

Actions (8)

Tool	Description
mark_read	Mark as read/unread
flag_email	Flag/unflag email
set_flag_color	Set flag color (7 colors)
set_background_color	Set email background color
mark_as_junk	Mark as junk/not junk
move_email	Move to another mailbox
copy_email	Copy to another mailbox
delete_email	Delete email (to trash)

Compose (5)

Tool	Description
compose_email	Send new email (supports attachments)
reply_email	Reply to email
forward_email	Forward email
redirect_email	Redirect email (keeps original sender)
open_mailto	Open mailto URL

Drafts (2)

Tool	Description
list_drafts	List draft emails
create_draft	Create a draft (supports attachments)

Attachments (2)

Tool	Description
list_attachments	List email attachments
save_attachment	Save attachment to disk

VIP (1)

Tool	Description
list_vip_senders	List VIP senders

Rules (5)

Tool	Description
list_rules	List mail rules
get_rule_details	Get rule details
create_rule	Create a new rule
delete_rule	Delete a rule
enable_rule	Enable/disable a rule

Signatures (2)

Tool	Description
list_signatures	List email signatures
get_signature	Get signature content

SMTP (1)

Tool	Description
list_smtp_servers	List SMTP servers

Sync (2)

Tool	Description
check_for_new_mail	Check for new mail
synchronize_account	Sync IMAP account

Utilities (4)

Tool	Description
extract_name_from_address	Extract name from email address
extract_address	Extract email from full address
get_mail_app_info	Get Mail.app info
import_mailbox	Import mailbox from file

---

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)

Index	Color
0	Red
1	Orange
2	Yellow
3	Green
4	Blue
5	Purple
6	Gray
-1	Clear

Background Colors (set_background_color)

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

---

Troubleshooting

Problem	Solution
Server disconnected	Rebuild with swift build -c release
Not allowed to send Apple events	Add permissions in System Settings > Automation
Mail.app not responding	Ensure Mail.app is running with configured accounts
Commands timing out	Large mailboxes take longer; try specific searches

---

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!