Apple Mail MCP Server

This is an experimental Model Context Protocol (MCP) server that enables programmatic interaction with Apple Mail.app through any MCP-compatible client. The server:

• Implements the MCP specification (version 2024-11-05)
• Communicates via JSON-RPC 2.0 over stdin/stdout
• Provides 14 tools for email operations
• Runs as a single compiled binary with no dependencies
• Works with any MCP-compatible client

Why Use This?

Privacy-First Email AI Integration: Instead of granting AI services OAuth access to your Gmail, Outlook, or iCloud accounts, this server lets AI interact with your local Mail.app.

• No persistent API access - AI can't independently access your email accounts
• Query-based access only - AI sees only emails you explicitly request, not your entire inbox
• Operation logging - In-memory audit log of operations (last 1000 entries with timestamps)
• Local LLM compatible - Use with local models (Ollama, LM Studio, etc.) to keep email content completely on-device

Perfect for privacy-conscious users who want AI email assistance without surrendering OAuth tokens or direct account credentials to external services.

Tip

For maximum privacy, pair this with a local LLM so no email data ever leaves your machine.

Important

This software is highly experimental. It serves a real use case and I use it regularly, but it is still rough around the edges. Keep that in mind.

---

Core Operations

• Search messages with filters (sender, subject, date, status)
• Send emails with validation
• Read messages with content and metadata
• List mailboxes and folder structure
• Mark as read/unread with bulk operations
• Attachment support (send, list, save)
• Move messages between mailboxes
• Flag messages with colors
• Create mailboxes and organize structure
• Delete messages (trash or permanent)
• Reply to messages (single or reply-all)
• Forward messages to recipients

Technical Features

The project is built with Go for performance, type safety, and easy deployment in mind.

• Type-safe implementation with Go's static typing
• Concurrent operations using goroutines
• Single binary distribution (no runtime dependencies)
• Input validation and sanitization
• Operation logging for audit trail
• Thread-safe operations with proper synchronization

Prerequisites

• macOS 10.15 (Catalina) or later
• Apple Mail configured with at least one account
• MCP-compatible client (e.g., Raycast, or other MCP clients)
• Go 1.21+ (for building from source only)

Quick Start

1. Build and Install

# Build the binary
make build

# Install to system (requires sudo automatically)
make install

This creates a binary at /usr/local/bin/apple-mail-mcp.

Why sudo? The default installation writes to /usr/local/bin, which is a system directory that requires administrator privileges. This ensures the binary is available system-wide and can be accessed by MCP clients like Raycast.

Alternative: Install to user directory (no sudo) - If you prefer to avoid sudo:

# Install to ~/.local/bin (no sudo required)
PREFIX=~/.local make install

# Or any other directory you own
PREFIX=/path/to/your/directory make install

NOTE: Make sure to update your MCP client configuration to use the custom path (e.g., ~/.local/bin/apple-mail-mcp).

2. Configure Your MCP Client

For Raycast

Raycast has built-in MCP server support. You can install the Apple Mail MCP server using one of two methods:

Method 1: Install Server Command (Recommended)

1. Open Raycast and run the Install Server command
2. Fill in the form with the following details:
   • Name: apple-mail
   • Command: /usr/local/bin/apple-mail-mcp
   • Leave Arguments empty
3. Click Install

Method 2: JSON Configuration

1. Copy this JSON configuration to your clipboard:

{
  "apple-mail": {
    "command": "/usr/local/bin/apple-mail-mcp"
  }
}

2. Open Raycast and run the Install Server command
3. Raycast will automatically pre-fill the form from your clipboard
4. Click Install

Alternative: Edit Config File Directly

For advanced users, you can edit the configuration file directly:

1. Run the Manage Servers command in Raycast
2. Use the Show Config File in Finder action
3. Edit mcp-config.json to add the server:

{
  "mcpServers": {
    "apple-mail": {
      "command": "/usr/local/bin/apple-mail-mcp"
    }
  }
}

Usage:

Once configured, you can use Apple Mail tools in Raycast AI:

@apple-mail Search for unread emails from john@example.com
@apple-mail Send an email to alice@example.com with subject "Meeting" 

The @apple-mail mention will automatically detect and use the available Apple Mail tools. You can use this in Quick AI, AI Chat, or custom AI Commands.

For more details, see the Raycast MCP Manual.

For Other MCP Clients

Consult your client's documentation. The server communicates via JSON-RPC 2.0 over stdin/stdout and outputs logs to stderr.

3. Restart Your MCP Client

Quit and reopen your MCP client application to load the server.

Usage

Basic Examples

Once configured with your MCP client, you can perform these operations:

Search for emails:

Find all unread emails from john@example.com

Read a message:

Show me the content of the most recent email

Send an email:

Send an email to alice@example.com with subject "Meeting" saying "Let's meet tomorrow"

List mailboxes:

List all my mailboxes

Work with attachments:

Save all attachments from the latest email to ~/Downloads

Organize emails:

Move this email to the Archive folder
Flag this email as red

Reply and forward:

Reply to this email saying "Thanks"
Forward this email to bob@example.com

Search Filters

You can combine multiple filters:

• By sender: "from john@example.com"
• By subject: "with subject containing invoice"
• By status: "unread emails" or "read emails"
• By date: "from last week", "in the last 3 days"
• By folder: "in my Archive folder"

Available Tools

The server provides 14 tools that can be called via the MCP protocol:

Tool	Description
list_mailboxes	List all mailboxes for an account
search_messages	Search messages with filters
get_message	Get full message details including content
send_email	Send email with validation
mark_as_read	Mark messages as read or unread
send_email_with_attachments	Send email with file attachments
get_attachments	List attachments from a message
save_attachments	Save attachments to disk
move_messages	Move messages between mailboxes
flag_message	Set color flags (red, yellow, blue, etc.)
create_mailbox	Create new mailbox/folder
delete_messages	Delete messages (trash or permanent)
reply_to_message	Reply to a message
forward_message	Forward a message to recipients

Development

For comprehensive technical documentation including architecture details, performance characteristics, communication protocols, data models, AppleScript integration patterns, and security implementation, see docs/TECHNICAL.md.

Building

# Development build
make build

# Optimized release build
make build-release

# Build for all platforms
make build-all  # darwin-amd64 and darwin-arm64

# Clean build artifacts
make clean

Testing

# Run all tests
make test

Troubleshooting

For comprehensive troubleshooting information including debugging with Raycast, common issues, log viewing, manual server testing, and system checks, see the Troubleshooting Guide.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

Security

For security issues, please open a GitHub issue with the "security" label or contact the maintainers directly.

Security Features

• Input validation on all operations
• AppleScript injection prevention
• Email address validation
• File type restrictions for attachments
• Path traversal prevention
• Bulk operation limits
• Operation audit logging
• Thread-safe concurrent operations

Related Resources

• MCP Protocol Specification
• Apple Mail AppleScript Dictionary
• Go Documentation

License

MIT License