IMAP MCP Pro

An enterprise-grade Model Context Protocol (MCP) server that provides production-ready IMAP email integration with advanced reliability features, comprehensive monitoring, and secure account management.

Professional Edition — Enhanced fork with Level 1-3 reliability features, circuit breaker pattern, metrics, and bulk operations for commercial and large-scale deployments.

📜 License at a glance

Free for personal, educational, and non-profit use. Paid commercial license required for any business, SaaS, revenue-generating, or multi-tenant deployment.

Contact for commercial licensing: colin.bitterfield@templeofepiphany.com Full terms: LICENSE · License section below

Features

100+ MCP tools across email/folder/account/category/scoring/subscription/dns-firewall/usercheck/staging/cache/diagnostics — every IMAP4rev2 (RFC 9051) operation we use is exposed. See the full categorized list with exact count in docs/TOOL_CATALOG.md (generated from the manifest on every build), or run imap_list_tools for the live catalog at runtime.

Core Features

• 🔐 Secure Account Management: Encrypted credential storage with AES-256 encryption
• 🚀 Connection Pooling: Efficient IMAP connection management
• 📧 Comprehensive Email Operations: Search, read, mark, delete emails
• ✉️ Email Sending: Send, reply, and forward emails via SMTP
• 📁 Folder Management: List folders, check status, get unread counts
• 🔄 Multiple Account Support: Manage multiple IMAP accounts simultaneously
• 🛡️ Type-Safe: Built with TypeScript for reliability
• 🌐 Web-Based Setup Wizard: Easy account configuration with provider presets
• 📱 15+ Email Providers: Pre-configured settings for Gmail, Outlook, Yahoo, and more
• 🔗 Auto SMTP Configuration: Automatic SMTP settings based on IMAP provider

Local Message Cache + Auto-installed Skills (v2.17.0+)

• Local SQLite header cache for fast sender enumeration. imap_sync_folder_cache populates a per-folder cache; imap_search_cache runs group_by_sender / by_domain / by_address queries against it in milliseconds. Validated end-to-end against a 1500-message INBOX: cold sync 1.7s, warm group-by-sender 4ms.
• UIDVALIDITY-aware delta sync: subsequent syncs only fetch new UIDs. Mailbox renumbering is detected automatically and triggers a full resync.
• Cache-miss is explicit: imap_search_cache returns a structured cache_miss error when a folder has not been synced — no silent IMAP fallback. The skill orchestrates the order.
• Auto-installed skills: bundled Claude skills (unsubscribe-cleanup in v2.17.0) are copied to ~/.claude/skills/imap-mcp-pro/ on server startup. Idempotent: skips when versions match, updates when the bundle is newer, preserves on-disk content with a higher version. Disable via IMAP_MCP_SKIP_SKILLS_INSTALL=1.
• Skill updates from public GitHub (v2.17.4+): two new tools, imap_check_skill_updates and imap_update_skills, let you pull newer skill versions from this repo without reinstalling the .mcpb. No PAT needed — the default source is the MCP's own public repo. See docs/SKILLS.md for the full guide including the trust model.

v2.0 Reliability & Attachments (v2.15.0+)

• Auto-Sent-folder placement: every imap_send_email archives to the right Sent folder by provider (Gmail / Outlook / iCloud / Fastmail / Yahoo / Hostinger / Zoho / GMX / ProtonMail). Bcc preserved in the archive copy per RFC 5322 §3.6.3. Failures queue for background retry, not lost.
• Pooled SMTP with classified retry: nodemailer pool, exponential backoff for transient failures, immediate surface (no retry) for auth failures with provider-specific guidance (e.g. "Gmail requires an app password, generate at...").
• Path-based attachments (attachmentPaths): pass absolute file paths instead of base64. Server validates against an allowed-dirs whitelist (with per-user override), realpath + symlink-target check, size caps, RFC 2183 filename sanitization.
• Chunked attachment uploads: for clients without server filesystem access. 4-tool workflow (stage_init → stage_append × N → stage_finalize → imap_send_email stagedAttachmentIds=[...]). Out-of-order chunks reassemble; duplicate chunkIndex is idempotent; SHA-256 verification on finalize.
• Diagnostic tools: imap_test_smtp, imap_test_sent_folder, imap_get_smtp_metrics, imap_list_unarchived_sends, imap_list_staged_attachments.

Enterprise Features (Pro Edition)

Level 1: Enhanced Connectivity

• ⚡ Enhanced Keepalive: RFC 2177 compliant NOOP commands every 29 minutes
• 🔌 Connection Monitoring: Real-time connection health tracking
• ✅ Connection Validation: Proactive connection state verification

Level 2: Advanced Reliability

• 🔄 Automatic Reconnection: Exponential backoff (1s → 2s → 4s → 8s → 60s max)
• ♻️ Retry Logic: Transparent retry wrapper for all operations (max 5 attempts)
• 🏥 Health Checks: Periodic NOOP every 29 minutes to prevent timeouts
• 📊 Connection State Machine: DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → ERROR
• ⚡ Bulk Operations: Efficient bulk delete, read, and mark operations

Level 3: Production-Grade Resilience

• 🛡️ Circuit Breaker: Prevents cascading failures (5 failures opens, 2 successes closes)
• 📦 Operation Queue: Queues operations during outages, replays when reconnected (1000 max)
• 📈 Comprehensive Metrics: Per-connection and per-operation metrics (ops, success rate, latency, uptime%)
• 🎯 Graceful Degradation: Read-only mode, result caching (5-min TTL), fallback to last known good data
• 🔍 Enhanced Monitoring: Real-time metrics via MCP tools (imap_get_metrics, imap_get_operation_metrics)

Multi-Tenant / MSP Deployments

🏢 Commercial License Available for MSPs

IMAP MCP Pro supports multi-user configurations for Managed Service Providers (MSPs) with a commercial license:

• 👥 User Isolation: Complete data isolation between customers
• 🔐 Per-Customer Authentication: Separate credentials for each tenant
• 🛡️ Role-Based Access Control: Admin and user roles with granular permissions
• 📊 Usage Tracking: Per-customer API usage and metrics
• 🎛️ Centralized Management: Manage multiple customer deployments from single installation

Configuration:

{
  "mcpServers": {
    "imap-customer-a": {
      "env": {
        "MCP_USER_ID": "customer-a"
      }
    },
    "imap-customer-b": {
      "env": {
        "MCP_USER_ID": "customer-b"
      }
    }
  }
}

Contact for Commercial Licensing:

• Email: colin.bitterfield@templeofepiphany.com
• Commercial license required for MSP/multi-tenant deployments
• Noncommercial use is free under the PolyForm Noncommercial License 1.0.0

Installation

Claude Desktop Extension (.mcpb) — Recommended for end users

The fastest path to a working setup is to install IMAP MCP Pro as a Claude Desktop Extension (.mcpb). This bundles everything (Node runtime, dependencies, native modules) into one archive and renders a native settings panel in Claude Desktop — no terminal, no JSON editing.

1. Download the latest .mcpb for your platform from the Releases page (e.g. imap-mcp-pro-2.14.0-macos-arm64.mcpb).
2. In Claude Desktop, open Settings → Extensions → Install Extension… and select the downloaded file.
3. Fill in the settings panel that appears:
   • Data Directory — where to store the database and cache (default: ~/.imap-mcp-pro)
   • Log Level — INFO is fine for day-to-day; DEBUG for troubleshooting
   • Maximum Attachment Size — default 25 MiB
   • Allowed Attachment Directories — optional, only needed for path-based attachment sends
   • Encryption Key — leave blank to auto-generate a file-based key (stored at ~/.imap-mcp/.encryption-key, mode 600); credentials are encrypted with AES-256-GCM (recommended)
   • User ID — default for single-user installs
4. Click Enable. Run a quick test by asking Claude What IMAP accounts do I have?.

To add accounts after install, ask Claude to use imap_add_account_auto (with provider auto-detection) or use the Web UI: imap-setup from the command line.

To upgrade, download a newer .mcpb and re-install — your data directory is preserved.

macOS — Package Installer (Recommended)

Download the latest .dmg from the Releases page:

1. Open IMAP-MCP-Pro-x.x.x.dmg
2. Double-click the .pkg inside
3. Follow the installer — it will:
   • Prompt for the Web UI port (default: 4500)
   • Offer to configure Claude Desktop automatically (if installed)
   • Install the ImapMCPControl menu bar app
   • Register and start the background service

After install the envelope icon appears in your menu bar. Use Preferences… (⌘,) to change settings at any time.

What gets installed:

macOS — Upgrade