ABMIC — A Better MCP Server for iCloud Mail and IMAP

A production-hardened Model Context Protocol (MCP) server for iCloud Mail, built for real-world use with AI agents like Claude. Manage thousands of emails reliably — search, move, flag, delete, and send — without crashes or data loss.

Forked from minagishl/icloud-mail-mcp — original work by minagishl. Thank you for the solid foundation!

Why ABMIC?

The original icloud-mail-mcp is a great starting point, but when used in production with large mailboxes (30,000+ emails) and AI agents performing bulk operations, several critical issues surface. ABMIC addresses all of them:

Critical Bug Fixes

Bug	Impact	Fix
moveMessages ignored provided message IDs	Used search(['ALL']) internally — moved every message in the mailbox instead of the targeted ones	Now uses the provided UIDs directly with imap.move()
setFlags ignored provided message IDs	Same search(['ALL']) bug — flagged/unflagged all messages	Now uses provided UIDs directly
deleteMessages ignored provided message IDs	Same bug — would delete all messages in the mailbox	Now uses provided UIDs with addFlags(['\\Deleted']) + expunge()
getMailboxes crashed with circular JSON	IMAP box objects contain circular parent/children references	Added sanitizeBoxes() to strip circular refs before serialization

Performance & Stability Improvements

Improvement	Before	After
Header-only fetching	getMessages and searchMessages downloaded full email bodies + attachments (bodies: '') — caused OOM crashes on large result sets	Fetches only HEADER.FIELDS (FROM TO SUBJECT DATE MESSAGE-ID) — 100x lighter, no more crashes
IMAP auto-reconnection	Connection drops between MCP calls caused silent failures	ensureConnected() checks imap.state before every operation; automatically destroys dead connections and reconnects
Proper UID tracking	Message IDs used parsed.messageId (the Message-ID header) — unusable for IMAP operations	All methods now return IMAP UIDs via attrs.uid, consistent across move/flag/delete operations
Sorted results	Messages returned in arbitrary IMAP fetch order	Results sorted by date (most recent first)

New Features

Feature	Description
Email alias support	Send from an alias (e.g., user@customdomain.com) via ICLOUD_SEND_FROM env var
Sent folder copy	Sent emails are automatically copied to the "Sent Messages" IMAP folder, so they appear in all mail clients
Robust connection lifecycle	Dedicated createImapInstance() factory, connected state tracking, and event-based cleanup on close/end/error

Installation

git clone https://github.com/zany92/abmic.git
cd abmic
npm install   # or pnpm install
npm run build

Configuration

Claude Desktop / Claude Code

Add to your MCP server configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "icloud-mail": {
      "command": "node",
      "args": ["/path/to/abmic/dist/index.js"],
      "env": {
        "ICLOUD_EMAIL": "you@icloud.com",
        "ICLOUD_APP_PASSWORD": "xxxx-xxxx-xxxx-xxxx",
        "ICLOUD_SEND_FROM": "you@yourdomain.com"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
ICLOUD_EMAIL	Yes	Your iCloud email address (e.g., user@icloud.com)
ICLOUD_APP_PASSWORD	Yes	App-specific password (generate one here)
ICLOUD_SEND_FROM	No	Email alias to use as the "From" address when sending

Prerequisites

1. An iCloud account with Mail enabled
2. Two-factor authentication enabled
3. An app-specific password (not your main iCloud password)

Available Tools

Email Operations

• get_messages — List recent emails from any mailbox (headers only, fast)
• search_messages — Search by query, sender, date range, read status
• send_email — Send emails (supports alias via ICLOUD_SEND_FROM)
• move_messages — Move emails between folders using IMAP UIDs
• delete_messages — Delete specific emails by UID
• set_flags — Add/remove flags (\Seen, \Flagged, \Deleted, etc.)
• mark_as_read — Shortcut to mark messages as read
• download_attachment — Download a specific attachment from a message
• auto_organize — Apply rule-based organization (sender/subject matching)

Mailbox Management

• get_mailboxes — List all IMAP folders (with nested subfolder support)
• create_mailbox — Create new folders (supports paths like Parent/Child)
• delete_mailbox — Delete folders (with system folder protection)

System

• test_connection — Verify IMAP and SMTP connectivity
• check_config — Check environment variable configuration

Architecture

src/
  index.ts                    # MCP server entry point, tool definitions
  lib/
    icloud-mail-client.ts     # Core IMAP/SMTP client with all fixes
  types/
    config.ts                 # TypeScript type definitions

Key design decisions:

• UID-based operations throughout — all message IDs are IMAP UIDs, not sequence numbers or Message-ID headers
• Headers-only for listing/searching — full body fetch only when explicitly needed (attachments)
• Defensive reconnection — every IMAP method calls ensureConnected() before operating
• No circular references — sanitizeBoxes() ensures JSON-safe mailbox listings

iCloud Mail Server Settings

Protocol	Server	Port	Security
IMAP	imap.mail.me.com	993	TLS/SSL
SMTP	smtp.mail.me.com	587	STARTTLS

Development

npm run dev          # Start with inspector
npm run build        # Build to dist/
npm run typecheck    # TypeScript checking
npm run test         # Run tests (vitest)
npm run lint         # ESLint
npm run format       # Prettier

Credits

This project is a fork of icloud-mail-mcp by minagishl, originally built during Hack Club's Summer of Making. The original project provided the MCP server scaffold, tool definitions, IMAP/SMTP integration, and test suite.

ABMIC extends it with production-critical fixes discovered while managing a 30,000+ email iCloud mailbox with Claude as an AI agent — including the UID bugs that could silently move or delete an entire mailbox, the OOM crashes from full-body fetching, and the connection reliability issues during long-running sessions.

License

MIT License — see LICENSE for details.

Copyright (c) 2025 Minagishl (original work), 2026 Vincent Picou (ABMIC modifications)