iCloud Mail MCP Server

A Model Context Protocol (MCP) server for integrating with iCloud Mail using App Password authentication. This server provides tools to read, send, and manage emails through iCloud’s IMAP and SMTP services.

Development logs for this project are being shared on Hack Club’s Summer of Making. Check it out to follow the development journey!

Features

• Secure Authentication: Uses App-specific passwords for secure iCloud Mail access
• Email Management: Read, send, and organize emails
• Mailbox Operations: List mailboxes, mark messages as read
• Attachment Support: Handle email attachments
• MCP Integration: Seamless integration with MCP-compatible clients

Prerequisites

1. iCloud Account: You need an active iCloud account with Mail enabled
2. App Password: Generate an app-specific password for Mail access:
   • Sign in to appleid.apple.com
   • Go to “Sign-In and Security” > “App-Specific Passwords”
   • Generate a new password for “Mail”
   • Save this password securely

Installation

# Clone the repository
git clone https://github.com/minagishl/icloud-mail-mcp.git
cd icloud-mail-mcp

# Install dependencies using pnpm
pnpm install

# Build the project
pnpm run build

Configuration

The server requires environment variables to be set for authentication. Configuration is done through your MCP client settings:

Environment Variables (Required)

Add to your MCP server configuration:

{
  "icloud-mail-mcp": {
    "command": "node",
    "args": ["/path/to/icloud-mail-mcp/dist/index.js"],
    "env": {
      "ICLOUD_EMAIL": "[email protected]",
      "ICLOUD_APP_PASSWORD": "your-app-specific-password"
    }
  }
}

Available Tools

Email Operations

get_messages

Retrieve email messages from a specified mailbox.

Parameters:

• mailbox (string, optional): Mailbox name (default: “INBOX”)
• limit (number, optional): Maximum number of messages to retrieve (default: 10)
• unreadOnly (boolean, optional): Retrieve only unread messages (default: false)

send_email

Send an email through iCloud Mail.

Parameters:

• to (string or array, required): Recipient email address(es)
• subject (string, required): Email subject
• text (string, optional): Plain text email body
• html (string, optional): HTML email body

mark_as_read

Mark email messages as read.

Parameters:

• messageIds (array, required): Array of message IDs to mark as read
• mailbox (string, optional): Mailbox name (default: “INBOX”)

move_messages

Move messages between mailboxes.

Parameters:

• messageIds (array, required): Array of message IDs to move
• sourceMailbox (string, required): Source mailbox name
• destinationMailbox (string, required): Destination mailbox name