Server data from the Official MCP Registry
Production IMAP & SMTP for Claude: multi-account email search, triage, send, and spam checks.
Production IMAP & SMTP for Claude: multi-account email search, triage, send, and spam checks.
Valid MCP server (2 strong, 1 medium validity signals). 13 known CVEs in dependencies (0 critical, 5 high severity) Imported from the Official MCP Registry.
4 files analyzed · 13 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Unverified package source
We couldn't verify that the installable package matches the reviewed source code. Proceed with caution.
Set these up before or after installing:
Environment variable: MCP_USER_ID
Environment variable: PORT
Environment variable: NODE_ENV
Environment variable: IMAP_MCP_VERSION
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-temple-of-epiphany-imap-mcp-pro": {
"env": {
"PORT": "your-port-here",
"NODE_ENV": "your-node-env-here",
"MCP_USER_ID": "your-mcp-user-id-here",
"IMAP_MCP_VERSION": "your-imap-mcp-version-here"
},
"args": [
"-y",
"@temple-of-epiphany/imap-mcp-pro"
],
"command": "npx"
}
}
}From the project's GitHub README.
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
95 MCP tools across email/folder/account/category/scoring/subscription/dns-firewall/usercheck/staging/cache/diagnostics — every IMAP4rev2 (RFC 9051) operation we use is exposed.
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.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.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.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.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.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.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.imap_test_smtp, imap_test_sent_folder, imap_get_smtp_metrics, imap_list_unarchived_sends, imap_list_staged_attachments.🏢 Commercial License Available for MSPs
IMAP MCP Pro supports multi-user configurations for Managed Service Providers (MSPs) with a commercial license:
Configuration:
{
"mcpServers": {
"imap-customer-a": {
"env": {
"MCP_USER_ID": "customer-a"
}
},
"imap-customer-b": {
"env": {
"MCP_USER_ID": "customer-b"
}
}
}
}
Contact for Commercial Licensing:
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.
.mcpb for your platform from the Releases page (e.g. imap-mcp-pro-2.14.0-macos-arm64.mcpb).~/.imap-mcp-pro)INFO is fine for day-to-day; DEBUG for troubleshootingdefault for single-user installsWhat 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.
Download the latest .dmg from the Releases page:
IMAP-MCP-Pro-x.x.x.dmg.pkg insideAfter install the envelope icon appears in your menu bar. Use Preferences… (⌘,) to change settings at any time.
What gets installed:
| Path | Contents |
|---|---|
~/.local/share/imap-mcp-pro/ | Server files, bundled Node.js runtime |
~/Applications/ImapMCPControl.app | Menu bar status/control app |
~/Library/LaunchAgents/com.templeofepiphany.imap-mcp-pro.plist | Background service definition |
~/.imap-mcp/ | Database and encryption keys (created on first run) |
Run the same .pkg installer over an existing installation. The installer detects the previous version and:
~/.imap-mcp/ (your accounts and data)git clone https://github.com/Temple-of-Epiphany/imap-mcp-pro.git
cd imap-mcp-pro
npm install
npm run build
make install
After installation, run the setup wizard:
npm run setup
Or if installed globally:
imap-setup
This will:
The setup wizard includes pre-configured settings for:
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):
{
"mcpServers": {
"imap-mcp-pro": {
"command": "/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/runtime/node/bin/node",
"args": ["/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/dist/index.js"],
"env": {
"MCP_USER_ID": "YOUR_USERNAME"
}
}
}
}
Restart Claude Desktop after any config change.
The following environment variables can be configured in your Claude Desktop configuration:
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_USER_ID | User identifier for multi-tenant deployments. Isolates accounts and data per user. | default | No |
PORT | Port number for the Web UI server | 4500 | No |
NODE_ENV | Node environment mode. Set to development for detailed error stack traces. | production | No |
IMAP_MCP_VERSION | Version identifier (automatically set by installer) | (package version) | No |
Example multi-user configuration:
{
"mcpServers": {
"imap-work": {
"command": "node",
"args": ["/path/to/imap-mcp-pro/dist/index.js"],
"env": {
"MCP_USER_ID": "work",
"PORT": "4500"
}
},
"imap-personal": {
"command": "node",
"args": ["/path/to/imap-mcp-pro/dist/index.js"],
"env": {
"MCP_USER_ID": "personal",
"PORT": "3001"
}
}
}
}
Note: Each MCP_USER_ID creates separate:
Once configured, the IMAP MCP server provides the following tools in Claude:
imap_add_account: Add a new IMAP account
Parameters:
- name: Friendly name for the account
- host: IMAP server hostname
- port: Server port (default: 993)
- user: Username
- password: Password
- tls: Use TLS/SSL (default: true)
imap_list_accounts: List all configured accounts
imap_remove_account: Remove an account
Parameters:
- accountId: ID of the account to remove
imap_connect: Connect to an account
Parameters:
- accountId OR accountName: Account identifier
imap_disconnect: Disconnect from an account
Parameters:
- accountId: Account to disconnect
imap_search_emails: Search for emails
Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- from, to, subject, body: Search criteria
- since, before: Date filters
- seen, flagged: Status filters
- limit: Max results (default: 50)
imap_get_email: Get full email content
Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID
imap_get_latest_emails: Get recent emails
Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- count: Number of emails (default: 10)
imap_mark_as_read/unread: Change email read status
Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID
imap_delete_email: Delete an email
Parameters:
- accountId: Account ID
- folder: Folder name
- uid: Email UID
imap_send_email: Send a new email
Parameters:
- accountId: Account ID to send from
- to: Recipient email address(es)
- subject: Email subject
- text: Plain text content (optional)
- html: HTML content (optional)
- cc: CC recipients (optional)
- bcc: BCC recipients (optional)
- replyTo: Reply-to address (optional)
- attachments: Array of attachments (optional)
- filename: Attachment filename
- content: Base64 encoded content
- path: File path to attach
- contentType: MIME type
imap_reply_to_email: Reply to an existing email
Parameters:
- accountId: Account ID
- folder: Folder containing the original email
- uid: UID of the email to reply to
- text: Plain text reply content (optional)
- html: HTML reply content (optional)
- replyAll: Reply to all recipients (default: false)
- attachments: Array of attachments (optional)
imap_forward_email: Forward an existing email
Parameters:
- accountId: Account ID
- folder: Folder containing the original email
- uid: UID of the email to forward
- to: Forward to email address(es)
- text: Additional text to include (optional)
- includeAttachments: Include original attachments (default: true)
imap_copy_email: Copy an email to another folder
Parameters:
- accountId: Account ID
- sourceFolder: Source folder name (default: INBOX)
- uid: Email UID to copy
- targetFolder: Target folder name
imap_bulk_copy_emails: Bulk copy multiple emails to another folder
Parameters:
- accountId: Account ID
- sourceFolder: Source folder name (default: INBOX)
- uids: Array of email UIDs to copy
- targetFolder: Target folder name
imap_move_email: Move an email to another folder
Parameters:
- accountId: Account ID
- sourceFolder: Source folder name (default: INBOX)
- uid: Email UID to move
- targetFolder: Target folder name
imap_bulk_move_emails: Bulk move multiple emails to another folder
Parameters:
- accountId: Account ID
- sourceFolder: Source folder name (default: INBOX)
- uids: Array of email UIDs to move
- targetFolder: Target folder name
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:
For explicit control over chunking behavior:
imap_bulk_mark_emails_chunked: Mark emails in chunks for large operations
Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- uids: Array of email UIDs to mark (supports 1000+ UIDs)
- operation: Mark operation (read, unread, flagged, unflagged, answered, unanswered, draft, not-draft, deleted, undeleted)
- chunkSize: Number of emails per chunk (default: 100)
Returns:
- processed: Number of successfully processed emails
- failed: Number of failed emails
- errors: Array of error details for failed chunks
imap_bulk_delete_emails_chunked: Delete emails in chunks for large operations
Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- uids: Array of email UIDs to delete (supports 1000+ UIDs)
- expunge: Permanently expunge deleted emails (default: false)
- chunkSize: Number of emails per chunk (default: 100)
Returns:
- processed: Number of successfully deleted emails
- failed: Number of failed emails
- errors: Array of error details for failed chunks
imap_bulk_get_emails_chunked: Fetch emails in chunks for large operations
Parameters:
- accountId: Account ID
- folder: Folder name (default: INBOX)
- uids: Array of email UIDs to fetch (supports 1000+ UIDs)
- fields: Fields to fetch (headers, body, or full)
- chunkSize: Number of emails per chunk (default: 100)
Returns:
- count: Number of successfully fetched emails
- totalRequested: Total number of UIDs requested
- emails: Array of fetched email objects
Use Case Example: Processing 1700 unread emails to mark bulk marketing messages for deletion:
imap_search_emails with seen: falseimap_bulk_get_emails_chunked with 1700 UIDs and chunkSize: 100imap_bulk_delete_emails_chunked with filtered UIDsBenefits:
imap_list_folders: List all folders
Parameters:
- accountId: Account ID
imap_folder_status: Get folder information
Parameters:
- accountId: Account ID
- folder: Folder name
imap_get_unread_count: Count unread emails
Parameters:
- accountId: Account ID
- folders: Specific folders (optional)
Use the menu bar app or run from the project directory:
# Interactive uninstall (prompts before removing data)
make uninstall
# Or run the script directly
distributions/osx/scripts/uninstall.sh
The uninstaller:
~/Applications/ImapMCPControl.app~/.local/share/imap-mcp-pro/~/.imap-mcp/ (your accounts and data)make uninstall
Your data lives in ~/.imap-mcp/ and consists of:
| File | Contents |
|---|---|
data.db | SQLite database — all accounts, settings, and history |
.encryption-key | AES-256 encryption key for stored passwords |
.key | Secondary key file |
Important: A backup without the key files cannot decrypt stored passwords. Always back up the entire
~/.imap-mcp/directory together.
Menu bar app: Preferences… → Database → Backup
Saves a .zip containing the database and both key files.
Command line:
# Save to ~/imap-mcp-pro-backup-YYYY-MM-DD.zip
make backup
# Save to a specific path
scripts/backup.sh /path/to/backup.zip
Menu bar app: Preferences… → Database → Restore
Select a .zip backup — the service stops, data is replaced, service restarts.
Command line:
make restore FILE=/path/to/backup.zip
# Or directly
scripts/restore.sh /path/to/backup.zip
The restore script stops the service before replacing files and restarts it automatically when done.
~/.imap-mcp/~/.imap-mcp/data.dbnpm run dev
npm run build
src/
├── index.ts # MCP server entry point
├── services/
│ ├── imap-service.ts # IMAP connection management
│ ├── smtp-service.ts # SMTP service for sending emails
│ └── database-service.ts # Encrypted account/user storage (SQLite)
├── tools/
│ ├── index.ts # Tool registration
│ ├── account-tools.ts # Account management tools
│ ├── email-tools.ts # Email operation tools (including send/reply/forward)
│ └── folder-tools.ts # Folder operation tools
└── types/
└── index.ts # TypeScript type definitions
Add an account: "Add my Gmail account with username john@gmail.com"
Check new emails: "Show me the latest 5 emails from my Gmail account"
Search emails: "Search for emails from boss@company.com in the last week"
Send an email: "Send an email to client@example.com 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 team@company.com"
Manage folders: "List all folders in my email account and show unread counts"
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:
{
"smtp": {
"host": "smtp.example.com",
"port": 587,
"secure": false
}
}
Gmail:
Outlook/Hotmail:
Yahoo:
Claude Desktop captures the server's stderr to per-server log files:
| Platform | Path |
|---|---|
| macOS | ~/Library/Logs/Claude/mcp-server-imap-mcp-pro.log |
| Windows | %APPDATA%\Claude\logs\mcp-server-imap-mcp-pro.log |
| Linux | ~/.local/state/Claude/logs/mcp-server-imap-mcp-pro.log |
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.
"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.
node dist/index.js --print-config-schema | jq .
Returns the full JSON Schema for ServerConfig — type, defaults, descriptions, validation bounds for every field.
node dist/index.js --print-tools-manifest | jq '.tools | length'
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 auditrfc/rfc9051.txtFree 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.
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:
You may make changes and new works for any permitted (noncommercial) purpose. (PolyForm Noncommercial imposes no share-alike/copyleft obligation.)
A paid commercial license is required before you may use this software for any of the following:
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.
Contact: colin.bitterfield@templeofepiphany.com 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.
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.
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.
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:
For major changes, please open an issue first to discuss what you would like to change.
Be the first to review this server!
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption