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": "your-email@icloud.com",
      "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

search_messages

Search for messages using various criteria.

Parameters:

• query (string, optional): Search query text (searches in subject, from, body)
• mailbox (string, optional): Mailbox name (default: "INBOX")
• limit (number, optional): Maximum number of messages to retrieve (default: 10)
• dateFrom (string, optional): Start date for search (YYYY-MM-DD format)
• dateTo (string, optional): End date for search (YYYY-MM-DD format)
• fromEmail (string, optional): Filter by sender email address
• unreadOnly (boolean, optional): Search only unread messages (default: false)

delete_messages

Delete messages from a mailbox.

Parameters:

• messageIds (array, required): Array of message IDs to delete
• mailbox (string, optional): Mailbox name (default: "INBOX")

set_flags

Set flags on messages (read, unread, flagged, etc.).

Parameters:

• messageIds (array, required): Array of message IDs to set flags on
• flags (array, required): Array of flags to set (e.g., ["\Seen", "\Flagged"])
• mailbox (string, optional): Mailbox name (default: "INBOX")
• action (string, optional): Whether to "add" or "remove" the flags (default: "add")

download_attachment

Download an attachment from a specific message.

Parameters:

• messageId (string, required): Message ID containing the attachment
• attachmentIndex (number, optional): Index of the attachment to download (0-based, default: 0)
• mailbox (string, optional): Mailbox name (default: "INBOX")

auto_organize

Automatically organize emails based on rules (sender, subject keywords, etc.).

Parameters:

• rules (array, required): Array of organization rules with conditions and actions
• sourceMailbox (string, optional): Source mailbox to organize (default: "INBOX")
• dryRun (boolean, optional): If true, only shows what would be organized without moving emails (default: false)

Rule Structure:

{
  "name": "Rule name",
  "condition": {
    "fromContains": "sender keyword",
    "subjectContains": "subject keyword"
  },
  "action": {
    "moveToMailbox": "destination folder"
  }
}

Mailbox Management

get_mailboxes

List all available mailboxes in your iCloud Mail account.

Parameters: None

create_mailbox

Create a new mailbox (folder) in your iCloud Mail account.

Parameters:

• name (string, required): Name of the mailbox to create

delete_mailbox

Delete an existing mailbox (folder) from your iCloud Mail account.

Parameters:

• name (string, required): Name of the mailbox to delete

Safety Features:

• Prevents deletion of system mailboxes (INBOX, Sent, Trash, Drafts, Junk)
• Validates mailbox name input
• Provides detailed error messages for common issues

System Tools

test_connection

Test the email server connection to verify IMAP and SMTP connectivity.

Parameters: None

check_config

Check if environment variables are properly configured and show connection status.

Parameters: None

Usage Example

Getting Started

Start the MCP server:

# With environment variables (recommended)
ICLOUD_EMAIL="your-email@icloud.com" ICLOUD_APP_PASSWORD="your-app-password" pnpm run start

# Or start normally and configure manually
pnpm run start

Email Operations

Get recent messages:

{
  "tool": "get_messages",
  "arguments": {
    "limit": 5,
    "unreadOnly": true
  }
}

Send an email:

{
  "tool": "send_email",
  "arguments": {
    "to": "recipient@example.com",
    "subject": "Hello from MCP",
    "text": "This email was sent using the iCloud Mail MCP server!"
  }
}

Move messages between mailboxes:

{
  "tool": "move_messages",
  "arguments": {
    "messageIds": ["message-id-1", "message-id-2"],
    "sourceMailbox": "INBOX",
    "destinationMailbox": "My Custom Folder"
  }
}

Mailbox Management

Create a new mailbox:

{
  "tool": "create_mailbox",
  "arguments": {
    "name": "My Custom Folder"
  }
}

Delete a mailbox:

{
  "tool": "delete_mailbox",
  "arguments": {
    "name": "My Custom Folder"
  }
}

System Tools

Test connection:

{
  "tool": "test_connection",
  "arguments": {}
}

Check configuration:

{
  "tool": "check_config",
  "arguments": {}
}

Security Notes

• App Passwords: Always use app-specific passwords, never your main iCloud password
• Secure Storage: Store your app password securely and never commit it to version control
• Connection Security: All connections use TLS/SSL encryption
• Minimal Permissions: The server only accesses Mail functionality

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm run dev

# Build the project
pnpm run build

# Type checking
pnpm run typecheck

# Run tests
pnpm run test

# Run linting
pnpm run lint

Testing

This project includes comprehensive test coverage using Vitest. The test suite covers:

Test Structure

• Total Tests: 29 tests across 3 test files
• Framework: Vitest with TypeScript support
• Coverage: Core functionality, type definitions, and configuration

Test Categories

1. Core Client Tests (src/lib/icloud-mail-client.test.ts)

• Constructor validation: Tests client creation with various configurations
• Email name extraction: Tests handling of different email formats
• Basic functionality: Tests core client behavior and configuration validation

2. Type Definition Tests (src/types/config.test.ts)

• iCloudConfig: Tests configuration object structure
• EmailMessage: Tests email message data types
• SendEmailOptions: Tests email sending parameter validation
• SearchOptions: Tests search parameter structures
• OrganizationRule: Tests email organization rule definitions
• Attachment: Tests attachment data structures

3. Server Configuration Tests (src/index.test.ts)

• Environment variables: Tests handling of configuration environment variables
• Credential masking: Tests security functions for hiding sensitive data
• Config validation: Tests basic configuration validation logic

Running Tests

# Run all tests once
pnpm run test:run

# Run tests in watch mode (interactive)
pnpm run test

# Run tests with UI interface
pnpm run test:ui

Test Features

• Type Safety: All tests are written in TypeScript without using any
• Mocking: External dependencies (IMAP, SMTP) are properly mocked
• Coverage: Tests cover both happy path and edge cases
• Isolation: Each test is independent and properly cleaned up
• Real-world scenarios: Tests reflect actual usage patterns

Troubleshooting

Authentication Issues

• Verify your app password is correct and hasn't expired
• Ensure two-factor authentication is enabled on your iCloud account
• Check that Mail is enabled in your iCloud settings

Connection Problems

• Verify internet connectivity
• Check if iCloud Mail servers are accessible
• Ensure firewall settings allow connections to imap.mail.me.com and smtp.mail.me.com

Email Not Sending

• Verify SMTP settings and authentication
• Check recipient email addresses are valid
• Ensure you're not hitting rate limits

iCloud Mail Server Settings

The server uses the following default settings for iCloud Mail:

• IMAP Server: imap.mail.me.com (Port: 993, SSL: Yes)
• SMTP Server: smtp.mail.me.com (Port: 587, TLS: Yes)

License

This project is licensed under the MIT License - see the LICENSE file for details.