Apple-Mail-MCP-Server/CLAUDE.md

CLAUDE.md - Apple Mail MCP Server

This file provides guidance for AI agents (Claude, etc.) when using this MCP server.

Overview

This MCP server enables AI assistants to interact with Apple Mail on macOS via AppleScript. All operations are local - no data leaves the user's machine.

Critical: Backslash Escaping

When sending content with backslashes to any tool, you MUST escape them.

The MCP protocol uses JSON for parameters. In JSON, \ is an escape character. To include a literal backslash:

You want	Send in JSON parameter
\	\\
\\	\\\\
C:\Users\	C:\\Users\\

Why This Matters

If you send a single backslash without escaping:

• The JSON parser interprets \ as an escape sequence
• Invalid sequences like \ (backslash-space) cause silent failures
• The email send/draft may fail with no clear error

Examples

Correct - Windows path in email:

body: "The file is at C:\\Users\\Documents\\report.pdf"

Incorrect - Will fail:

body: "The file is at C:\Users\Documents\report.pdf"

Tool Usage Tips

Using Message IDs (Required)

All message operations require an id parameter. Always get IDs first using list-messages or search-messages:

# List messages returns IDs
list-messages mailbox="INBOX"
→ Messages with IDs like "12345", "12346", etc.

# Use ID for all subsequent operations
get-message id="12345"
mark-as-read id="12345"
delete-message id="12345"
reply-to-message id="12345" body="Thanks!"

Recipient Arrays

The to, cc, and bcc parameters must always be arrays:

Correct:

{
  "to": ["bob@example.com"],
  "subject": "Hello"
}

Incorrect:

{
  "to": "bob@example.com",
  "subject": "Hello"
}

send-email vs create-draft

• Use send-email for immediate sending
• Use create-draft when the user should review first
• Recommendation: For important emails, use create-draft and tell the user to review in Mail.app

reply-to-message

• Set replyAll: true to reply to all recipients
• Set send: false to save as draft instead of sending immediately
• Default behavior: reply to sender only, send immediately

forward-message

• Requires message id and to array
• Optional body to prepend a message
• Set send: false to save as draft

Multi-account

• Default account is typically the first configured
• Use list-accounts to see available accounts
• Pass account parameter to target specific account

Error Handling

Error	Likely Cause
"Mail.app not responding"	Mail.app frozen or not running
"Message not found"	Message ID is invalid or message was deleted/moved
"Permission denied"	macOS automation permission needed
"Account not found"	Account name doesn't match exactly (case-sensitive)
"Failed to send email"	Network issue or Mail.app configuration problem
Silent failure	Backslash not escaped in content

Security Considerations

• Sending emails: Always confirm with user before sending. Recommend create-draft for review.
• Deleting messages: Warn user that deletion moves to Trash (can be recovered).
• Reading emails: May contain sensitive information - summarize rather than display full content when appropriate.

Example Workflows

Check for important emails

1. list-accounts → get available accounts
2. search-messages query="boss@company.com" → find emails from boss
3. get-message id="..." → read the full content

Send a reply safely

1. get-message id="..." → read original message
2. reply-to-message id="..." body="..." send=false → save as draft
3. Tell user to review in Mail.app before sending

Compose and send

1. create-draft to=["recipient@example.com"] subject="..." body="..."
2. Tell user: "I've created a draft. Review it in Mail.app and send when ready."
   OR if user confirms they want to send immediately:
3. send-email to=["recipient@example.com"] subject="..." body="..."

Forward an email

1. get-message id="..." → read the message to forward
2. forward-message id="..." to=["colleague@company.com"] body="FYI - see below"

Organize inbox

1. search-messages query="newsletter" → find newsletters
2. For each: move-message id="..." mailbox="Archive"

Testing Your Understanding

Before sending emails with paths or special characters, verify escaping:

• ~/path/to/file - No escaping needed (no backslashes)
• C:\Users\ - Needs escaping: C:\\Users\\
• file\ name.txt - Needs escaping: file\\ name.txt