
IMAP MCP Pro
io.github.Temple-of-Epiphany由 GitHub 账号 Temple-of-Epiphany 发布v2.39.0更新于 Oct 24, 2026
适用于 Claude 的生产级 IMAP 与 SMTP:多账户邮件搜索、分类处理、发送和垃圾邮件检查。
AI 翻译由 AI 模型根据下方的原文描述翻译,可能有误。
原文描述
Production IMAP & SMTP for Claude: multi-account email search, triage, send, and spam checks.
概览
IMAP MCP Pro 的本地 MCP 服务;无需登录;STDIO。
暂无 AI 概览:以下信息来自注册中心条目和服务本身。
安装
在 SourceWeft 中
- 打开 控制台中的 IMAP MCP Pro,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
IMAP MCP Pro
[License: Dual — Personal Free / Commercial Paid] [Latest release]
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: [email protected] 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_cachepopulates a per-folder cache;imap_search_cacherunsgroup_by_sender/by_domain/by_addressqueries 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_cachereturns a structuredcache_misserror when a folder has not been synced — no silent IMAP fallback. The skill orchestrates the order. - Auto-installed skills: bundled Claude skills (
unsubscribe-cleanupin 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 viaIMAP_MCP_SKIP_SKILLS_INSTALL=1. - Skill updates from public GitHub (v2.17.4+): two new tools,
imap_check_skill_updatesandimap_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. Seedocs/SKILLS.mdfor the full guide including the trust model.
v2.0 Reliability & Attachments (v2.15.0+)
- Auto-Sent-folder placement: every
imap_send_emailarchives 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; duplicatechunkIndexis 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:
Contact for Commercial Licensing:
- Email: [email protected]
- 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.
- Download the latest
.mcpbfor your platform from the Releases page (e.g.imap-mcp-pro-2.14.0-macos-arm64.mcpb). - In Claude Desktop, open Settings → Extensions → Install Extension… and select the downloaded file.
- Fill in the settings panel that appears:
- Data Directory — where to store the database and cache (default:
~/.imap-mcp-pro) - Log Level —
INFOis fine for day-to-day;DEBUGfor 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 —
defaultfor single-user installs
- Data Directory — where to store the database and cache (default:
- 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:
- Open
IMAP-MCP-Pro-x.x.x.dmg - Double-click the
.pkginside - 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
Run the same .pkg installer over an existing installation. The installer detects the previous version and:
- Preserves your port setting and Claude Desktop configuration
- Stops the service, replaces server files, then restarts automatically
- Does not touch
~/.imap-mcp/(your accounts and data)
Linux / Manual Installation
- Clone the repository:
- Install dependencies and build:
- Install and start the service:
Account Setup
Web-Based Setup Wizard (Recommended)
After installation, run the setup wizard:
Or if installed globally:
This will:
- Start a local web server
- Open your browser to the setup wizard
- Guide you through adding email accounts with pre-configured settings
Supported Email Providers
The setup wizard includes pre-configured settings for:
- Gmail / Google Workspace
- Microsoft Outlook / Hotmail / Live
- Yahoo Mail
- Apple iCloud Mail
- GMX
- WEB.DE
- IONOS (1&1)
- ProtonMail (with Bridge)
- Fastmail
- Hostinger
- Zoho Mail
- AOL Mail
- mailbox.org
- Posteo
- Custom IMAP servers
Configuration
Claude Desktop Configuration
macOS pkg installer: Claude Desktop is configured automatically during install. You can also manage it via Preferences… → Claude Desktop Integration in the menu bar app.
Manual configuration — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Restart Claude Desktop after any config change.
Environment Variables
The following environment variables can be configured in your Claude Desktop configuration:
Tool profiles
The server registers about 130 MCP tools. Some hosts announce all of them but surface none to the session (observed with the Claude Desktop Cowork bridge, #293). Set the Tool Profile extension option (or IMAP_MCP_TOOL_PROFILE) to choose how many are exposed:
imap_list_tools always reports the active profile and the names of the hidden tools. An unknown value falls back to full with a warning in the server log. Restart Claude Desktop after changing the option. The .mcpb manifest always lists the full catalog regardless of profile.
Example multi-user configuration:
Note: Each MCP_USER_ID creates separate:
- Account storage (database)
- CleanTalk API key configuration
- Web UI instance (on specified PORT)
- Session data and credentials
Usage
Once configured, the IMAP MCP server provides the following tools in Claude:
Account Management
-
imap_add_account: Add a new IMAP account
-
imap_list_accounts: List all configured accounts
-
imap_remove_account: Remove an account
-
imap_connect: Connect to an account
-
imap_disconnect: Disconnect from an account
Email Operations
-
imap_search_emails: Search for emails
-
imap_get_email: Get full email content
-
imap_get_latest_emails: Get recent emails
-
imap_mark_as_read/unread: Change email read status
-
imap_delete_email: Delete an email
-
imap_send_email: Send a new email
-
imap_reply_to_email: Reply to an existing email
-
imap_forward_email: Forward an existing email
-
imap_copy_email: Copy an email to another folder
-
imap_bulk_copy_emails: Bulk copy multiple emails to another folder
-
imap_move_email: Move an email to another folder
-
imap_bulk_move_emails: Bulk move multiple emails to another folder
Automatic Chunking (Smart Bulk Operations)
All bulk operations now automatically use chunking for >50 UIDs! You don't need to choose between regular and chunked tools - the system intelligently handles this for you.
How it works:
- ≤50 UIDs: Fast single-batch processing
- >50 UIDs: Automatic chunked processing (100 UIDs per chunk)
- Progress tracking: Real-time logging in server logs
- Error recovery: Continues processing if individual chunks fail
Chunked Bulk Operations (Large-Scale Processing)
For explicit control over chunking behavior:
-
imap_bulk_mark_emails_chunked: Mark emails in chunks for large operations
-
imap_bulk_delete_emails_chunked: Delete emails in chunks for large operations
-
imap_bulk_get_emails_chunked: Fetch emails in chunks for large operations
Use Case Example: Processing 1700 unread emails to mark bulk marketing messages for deletion:
- Search for unread emails:
imap_search_emailswithseen: false - Fetch headers in chunks:
imap_bulk_get_emails_chunkedwith 1700 UIDs andchunkSize: 100 - Filter marketing emails in your application logic
- Delete in chunks:
imap_bulk_delete_emails_chunkedwith filtered UIDs
Benefits:
- Prevents circuit breaker trips by processing in small batches
- Continues processing even if individual chunks fail
- Provides progress tracking and error reporting
- 100ms delay between chunks prevents server overload
Folder Operations
-
imap_list_folders: List all folders
-
imap_folder_status: Get folder information
-
imap_get_unread_count: Count unread emails
Removal
macOS
Use the menu bar app or run from the project directory:
The uninstaller:
- Stops and removes the LaunchAgent
- Removes
~/Applications/ImapMCPControl.app - Removes
~/.local/share/imap-mcp-pro/ - Forgets pkgutil receipts
- Prompts before removing
~/.imap-mcp/(your accounts and data) - Prompts before removing the Claude Desktop MCP entry
Linux
Backup and Restore
Your data lives in ~/.imap-mcp/ and consists of:
Important: A backup without the key files cannot decrypt stored passwords. Always back up the entire
~/.imap-mcp/directory together.
WAL mode (v2.34.0+): the database uses SQLite WAL journaling so several servers can share it (Claude Desktop runs one per host). Recent writes can sit in
data.db-waluntil checkpointed, so don't back up by copyingdata.dbwithcp. Use the backup below, orsqlite3 ~/.imap-mcp/data.db ".backup '/path/to/copy.db'".
Backup
Menu bar app: Preferences… → Database → Backup
Saves a .zip containing the database and both key files.
Command line:
The script takes a consistent snapshot with sqlite3 .backup (safe while servers are running), so the sqlite3 command-line tool must be installed.
Restore
Menu bar app: Preferences… → Database → Restore
Select a .zip backup — the service stops, data is replaced, service restarts.
Command line:
The restore script stops the service before replacing files and restarts it automatically when done.
Security
- Credentials are encrypted using AES-256-GCM encryption
- Encryption keys are stored separately in
~/.imap-mcp/ - Database is stored at
~/.imap-mcp/data.db - Never commit or share your encryption keys or database
Privacy Policy
IMAP MCP Pro runs entirely on your device and sends no data to the
publisher — there is no telemetry and no server operated by us. It processes
only the email accounts you configure; credentials are encrypted at rest
(AES-256-GCM) and all local files are owner-only. Data leaves your machine only
at your direction: to your own IMAP/SMTP servers, to optional integrations you
enable (UserCheck for spam checks, a DNS-over-HTTPS provider for firewall
checks), and to the Claude client you use. Data persists locally only until you
delete it (remove an account, clear the cache, or delete ~/.imap-mcp/).
Full policy — data collected, storage, third-party sharing, retention, and contact: PRIVACY.md.
Development
Running in Development Mode
Building
Project Structure
Example Usage in Claude
-
Add an account: "Add my Gmail account with username [email protected]"
-
Check new emails: "Show me the latest 5 emails from my Gmail account"
-
Search emails: "Search for emails from [email protected] in the last week"
-
Send an email: "Send an email to [email protected] with subject 'Project Update'"
-
Reply to emails: "Reply to the latest email from my boss"
-
Forward emails: "Forward the email with subject 'Meeting Notes' to [email protected]"
-
Manage folders: "List all folders in my email account and show unread counts"
Troubleshooting
Connection Issues
- Ensure your IMAP server settings are correct
- Check if your email provider requires app-specific passwords
- Verify that IMAP is enabled in your email account settings
- For sending emails, ensure your account has SMTP access enabled
SMTP Configuration
The server automatically configures SMTP settings based on your IMAP provider. If you need custom SMTP settings, you can specify them when adding an account:
Common IMAP Settings
-
Gmail:
- Host: imap.gmail.com
- Port: 993
- Requires app-specific password
-
Outlook/Hotmail:
- Host: outlook.office365.com
- Port: 993
-
Yahoo:
- Host: imap.mail.yahoo.com
- Port: 993
- Requires app-specific password
Troubleshooting
Where do logs go?
Claude Desktop captures the server's stderr to per-server log files:
Look for lines like [startup] stage=pre-handshake outcome=ok duration_ms=12 to confirm the server is starting cleanly. If pre-handshake exceeds 2 s, you'll see an outcome=warning line.
Common failures
"Configuration valid" but tools fail at runtime
Run node /path/to/server/dist/index.js --validate-config (or via the .mcpb extension's bundled server). It prints every resolved value and flags filesystem permission issues separately from schema errors.
Database errors on startup (exit 2)
Usually permissions on the data directory. Check database.path from --validate-config — the parent directory must be writable.
Tools return "warming up" responses on first call
Background services are still initializing (post-handshake stage). Wait a few seconds and retry. If it persists, check the log for an outcome=error line.
Server appears unresponsive in Claude Desktop
Most often a pre-handshake timeout. Confirm with --validate-config first; if that's OK, check the log for the pre-handshake duration_ms — anything over 2000 will time out.
Configuration not picking up env var
Run --validate-config and look at the [source] tag next to the field. Sources, highest precedence first: cli > env > file > default. If [default] is shown when you expected [env], the env var name may be wrong — see the canonical mapping in src/config/server-config.ts:ENV_VAR_MAPPING.
Inspecting the config schema
Returns the full JSON Schema for ServerConfig — type, defaults, descriptions, validation bounds for every field.
Inspecting the tool catalog
Documentation
EXAMPLES.md— worked Claude conversation transcripts for common workflowsdocs/SKILLS.md— bundled skills, auto-install behavior, GitHub-update tooling, contributor guidedocs/ARCHITECTURE.md— codebase map, startup stages, response-shape policy, contributor guidedocs/sdk_audit_2026-04-29.md— MCP SDK alignment audit- RFC 9051 (IMAP4rev2) full text in
rfc/rfc9051.txt
License
Free for personal use. Paid for commercial use.
This software is distributed under a Dual License Model: the PolyForm Noncommercial License 1.0.0 for noncommercial use, plus a separate commercial license for everything else. The license you operate under depends entirely on how you use the software.
✅ Noncommercial use — FREE (PolyForm Noncommercial License 1.0.0)
You may use, copy, modify, and distribute this software at no cost when your use is for a permitted (noncommercial) purpose under the PolyForm Noncommercial License, including:
- Personal email management on your own accounts
- Educational use (students, instructors, classroom)
- Academic research projects
- Internal operations of qualifying non-profit organizations
- Open source project development
- Evaluation, testing, and proof-of-concept work
You may make changes and new works for any permitted (noncommercial) purpose. (PolyForm Noncommercial imposes no share-alike/copyleft obligation.)
💼 Commercial License — PAID (required)
A paid commercial license is required before you may use this software for any of the following:
- Business email operations of a for-profit company
- Any SaaS product, hosted service, or paid offering
- Multi-tenant or MSP (Managed Service Provider) deployments
- Production deployments of revenue-generating services
- Re-distribution as part of a commercial product
- Use by an organization that generates revenue (other than qualifying non-profits' internal operations)
If your use isn't on the free list above, you need a commercial license — even if you're not directly charging users for the email feature.
Getting a commercial license
Contact: [email protected] Organization: Temple of Epiphany
Commercial license terms include support and maintenance, priority bug fixes, production deployment rights, and legal indemnification. Both perpetual and subscription options are available.
Not sure which applies to you?
If your use case isn't an obvious fit for the non-commercial list, default to assuming you need a commercial license and email us — happy to clarify.
Full legal terms: LICENSE.
Attribution
This project is an enterprise-enhanced fork of the original IMAP MCP Server created by Michael Nikolaus.
Original Project: https://github.com/nikolausm/imap-mcp-server Original Author: Michael Nikolaus Original License: MIT License (applies to base code only)
Temple of Epiphany has added extensive enterprise features (Levels 1-3) which are subject to the dual-license model above.
Contributing
We welcome contributions! For commercial use contributions, contributors agree that their contributions will be subject to the project's dual-license model.
Please feel free to submit Pull Requests for:
- Bug fixes
- Documentation improvements
- New features
- Performance enhancements
For major changes, please open an issue first to discuss what you would like to change.
来源:README.md,提交 82ab370
工具
0版本历史
2- v2.39.0最新Oct 20, 2026
- v2.34.0Sep 16, 2026
评分
已满足适用检查项的 40%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分
请在仓库或注册中心条目中声明许可证。