icloud-mail

This MCP server provides a bridge to iCloud Mail using App Password authentication, exposing a set of MCP-compatible tools to read, send, organize, and manage emails via iCloud's IMAP and SMTP services. Once running, clients can invoke tools such as get_messages, send_email, mark_as_read, move_messages, search_messages, delete_messages, set_flags, download_attachment, auto_organize, get_mailboxes, create_mailbox, delete_mailbox, test_connection, and check_config to perform common email tasks without handling raw IMAP/SMTP protocols directly. The server is designed to work behind an MCP client, taking input as tool names and argument payloads, and returning structured results that MCP clients can render or process further. To start, ensure you provide your iCloud credentials as environment variables (ICLOUD_EMAIL and ICLOUD_APP_PASSWORD) when launching, and point the server at its built dist index file. Typical usage involves sending JSON tool requests to the MCP endpoint and receiving responses with the requested data or status.

Prerequisites:

• Node.js installed on your system
• Access to a terminal or shell
• An iCloud account with Mail enabled and an App-Specific Password for authentication

Install steps:

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

2. Install dependencies (pnpm is used in the project; you can adapt to npm/yarn if preferred) pnpm install

3. Build the project pnpm run build

4. Run the server (provide credentials via environment variables or a secure config) ICLOUD_EMAIL="your-email@icloud.com" ICLOUD_APP_PASSWORD="your-app-specific-password" pnpm run start

5. Verify the server is running and accessible through your MCP client You can also run development commands as needed (pnpm run dev, pnpm run test, etc.)

Tips:

• Use App Passwords for iCloud access and store them securely; do not commit passwords to version control.
• Ensure network access to iCloud services (IMAP/SMTP) is allowed from your deployment environment.
• The provided configuration example uses the server key icloud-mail-mcp; adjust the mcpServers key to match your deployment naming conventions if needed.
• If you update code, rebuild with pnpm run build before restarting the server.
• When troubleshooting, use the check_config tool to verify environment variables are correctly recognized and the connection status of IMAP/SMTP is healthy.