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!
Model Context Protocol server for iCloud Mail management and email operations
ดาว
11
เครื่องมือ
—
อัปไทม์
—
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
iCloud Account: You need an active iCloud account with Mail enabled
App Password: Generate an app-specific password for Mail access:
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:
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="[email protected]" ICLOUD_APP_PASSWORD="your-app-password" pnpm run start
# Or start normally and configure manually
pnpm run start
{
"tool": "send_email",
"arguments": {
"to": "[email protected]",
"subject": "Hello from MCP",
"text": "This email was sent using the iCloud Mail MCP server!"
}
}
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