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"
- Find CheAppleMailMCP and enable permission for Mail.app
- 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!