iMail-mcp

# iCloud Mail MCP Server <a href="https://glama.ai/mcp/servers/@Racimy/iMail-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@Racimy/iMail-mcp/badge" /> </a> 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](https://summer.hackclub.com/projects/7559). 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](https://appleid.apple.com) - Go to "Sign-In and Security" > "App-Specific Passwords" - Generate a new password for "Mail" - Save this password securely ## Installation ```bash # 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: ```json { "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 <details> <summary><strong>Click to view all available tools</strong></summary> ### 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:** ```json { "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 </details> ## Usage Example <details> <summary><strong>Click to view usage examples</strong></summary> ### Getting Started **Start the MCP server:** ```bash # 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:** ```json { "tool": "get_messages", "arguments": { "limit": 5, "unreadOnly": true } } ``` **Send an email:** ```json { "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:** ```json { "tool": "move_messages", "arguments": { "messageIds": ["message-id-1", "message-id-2"], "sourceMailbox": "INBOX", "destinationMailbox": "My Custom Folder" } } ``` ### Mailbox Management **Create a new mailbox:** ```json { "tool": "create_mailbox", "arguments": { "name": "My Custom Folder" } } ``` **Delete a mailbox:** ```json { "tool": "delete_mailbox", "arguments": { "name": "My Custom Folder" } } ``` ### System Tools **Test connection:** ```json { "tool": "test_connection", "arguments": {} } ``` **Check configuration:** ```json { "tool": "check_config", "arguments": {} } ``` </details> ## 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 ```bash # 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 ```bash # 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](LICENSE) file for details.