Errol Mail

<p align="center">

</p>

<h1 align="center">Errol-Mail</h1>

<p align="center">
<a href="https://www.python.org/downloads/"></a>
<a href="https://www.apple.com/macos/"></a>
<a href="https://opensource.org/licenses/MIT"></a>
</p>

An MCP server that gives Claude comprehensive access to all of your email accounts in Apple Mail (via SQL, local file access, and AppleScript-only when needed). Ask your AI assistant questions like "Do I have any new emails in my work inbox needing my attention?", "Read all of my emails flagged with an 'Attention needed' flag and summarize them in order of priority", and so on. Email content is retrieved rapidly in batches. Apple Mail's flag system with different colors and labels is fully supported. Read/unread status and flags can be updated automatically (using a headless AppleScript approach). Old messages that haven't been downloaded to the local database can even be triggered to be downloaded (using AppleScript). A Claude Skill is included, which can be easily customized so you can teach your AI assistant exactly what to do when you ask.

Recent Additions

- Prompt Injection Defenses - Email content is wrapped in isolation tags, scanned for injection patterns, and escaped to prevent attacks. See Security for details.
- Performance Optimizations - Faster email listings and parallel parsing for threads with multiple messages.

Features

📬 Email Discovery

- Browse mailboxes - List all folders across all accounts - Search messages - Filter by subject, sender, date range - Unread/flagged - Quick access to messages needing attention - 7 flag colors - Filter by red, orange, yellow, green, blue, purple, gray - Custom flag labels - Use your Mail.app names ("Action needed", "Waiting")

📖 Email Reading

- Full content - Read complete emails with headers and body - Thread view - Read entire conversations chronologically - Smart quotes - Automatic removal of redundant quoted text - Thread summaries - Quick overview before diving deep

📎 Attachments

- List attachments - See all files in an email - Extract files - Save attachments to temp directory - Batch extract - Get all attachments at once - Auto cleanup - Remove old extracted files

✏️ Message Management (Headless via AppleScript)

- Read/unread status - Mark messages without opening Mail windows - Flag colors - Set any of 7 flag colors programmatically - Fully headless - All operations run silently in the background - Server sync - Changes automatically sync to IMAP/Exchange

📡 Server-Side Message Retrieval

- Availability check - Detect if emails exist only on server (not downloaded) - On-demand download - Fetch old emails from the server when needed - Silent download - Download emails and auto-close windows for batch operations - Access your entire archive - Read emails from years ago that aren't stored locally

Quick Start

1. Prerequisites

- macOS 12.0+ (Monterey or later)
- Python 3.9+
- Apple Mail configured with at least one account

2. Grant Full Disk Access

Errol reads Mail's database, which requires Full Disk Access. Run the diagnostic script to check your setup:

python3 check_fda.py

If access is working, you'll see:

✅ Successfully accessed Mail database (12,345 messages)

If not, the script tells you exactly what path to add to Full Disk Access. This is important because:
- macOS permissions apply to the actual binary, not symlinks
- Homebrew Python uses wrapper scripts that point to Python.app
- MCP hosts spawn Python as a child process, so adding the host app isn't enough

The script handles all of this and gives you the precise path to add.

<details>
<summary><b>Manual Setup (if you prefer)</b></summary>

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click + and add:
- Terminal users: Your terminal app (Terminal.app, iTerm2, Warp)
- Homebrew Python: The Python.app inside Cellar (run check_fda.py to find it)
- System Python: /usr/bin/python3
3. Restart your terminal or MCP client

</details>

3. Install

git clone https://github.com/jasondk/errol-mail.git
cd errol-mail
pip install -r requirements.txt

4. Configure MCP Client

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "errol": {
      "command": "python",
      "args": ["/absolute/path/to/errol-mail/server.py"]
    }
  }
}

For Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "errol": {
      "command": "python",
      "args": ["/absolute/path/to/errol-mail/server.py"]
    }
  }
}

5. Test

python server.py --test

Available Tools

Discovery Tools

| Tool | Description |
|------|-------------|
| list_mailboxes() | List all mailboxes with message counts |
| find_mailbox(term) | Find mailboxes by name |
| get_recent_messages(limit) | Recent messages from all folders |
| get_unread_messages(limit) | Unread messages only |
| get_folder_messages(folder, limit) | Messages in specific folder |
| search_messages(subject, sender, days_back) | Search with filters |
| get_flagged_messages(color, folder) | Filter by any of 7 flag colors |

Reading Tools

| Tool | Description |
|------|-------------|
| read_email(message_id) | Full email content |
| read_emails_batch(message_ids) | Read multiple emails in parallel (up to 20) |
| read_thread(message_id) | Entire conversation |
| get_thread_summary(message_id) | Thread overview |

Attachment Tools

| Tool | Description |
|------|-------------|
| list_attachments(message_id) | List email attachments |
| get_attachment(message_id, filename) | Extract one file |
| extract_all_message_attachments(message_id) | Extract all files |
| cleanup_attachments(hours) | Remove old extracts |

Message Modification Tools

| Tool | Description | Opens Window |
|------|-------------|--------------|
| mark_email_read(message_id) | Mark as read | No |
| mark_email_unread(message_id) | Mark as unread | No |
| set_email_flag(message_id, color) | Set flag color | No |
| clear_email_flag(message_id) | Remove flag | No |

Server-Side Tools

| Tool | Description | Opens Window |
|------|-------------|--------------|
| check_email_availability(message_id) | Check if local or server-only | No |
| download_email(message_id) | Download from server | Yes |
| download_email_silent(message_id) | Download and auto-close | Briefly |
| open_email_in_mail(message_id) | Open in Mail.app | Yes |

Utility Tools

| Tool | Description |
|------|-------------|
| list_flag_colors() | Show custom flag labels |
| cleanup_mail_windows() | Close all message windows |
| minimize_mail_app() | Minimize Mail to dock |

Usage Examples

Check what needs attention

"What unread emails do I have?"
"Show me flagged messages from the last week"
"Are there any emails from John about the project?"

Read and triage emails

"Read the thread about the budget proposal"
"Summarize the conversation with the marketing team"
"Mark message 698914 as read and flag it red"

Work with flagged messages

"Show me all my red-flagged action items"
"What orange messages am I waiting on?"
"Flag this email blue for reference"
"List flag colors to see my custom labels"

Process attachments

"What attachments are in the email about Q4 reports?"
"Extract the PDF from message 698519"

Handle server-only messages

…