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

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

Usage Example

# 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

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

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

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

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

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

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

{
  "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.