The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Email MCP listing page.
An MCP (Model Context Protocol) server providing comprehensive email capabilities via IMAP and SMTP.
Enables AI assistants to read, search, send, manage, schedule, and analyze emails across multiple accounts. Exposes 47 tools, 7 prompts, and 6 resources over the MCP protocol with OAuth2 support (experimental), email scheduling, calendar extraction, analytics, provider-aware label management, real-time IMAP IDLE watcher with AI-powered triage, customizable presets and static rules, and a guided setup wizard.
| Feature | email-mcp | Typical MCP email |
|---|---|---|
| Multi-account | ✅ | ❌ |
| Send / reply / forward | ✅ | ✅ |
| Drafts & templates | ✅ | ❌ |
| Labels & bulk ops | ✅ provider-aware | ❌ |
| Schedule future emails | ✅ | ❌ |
| Real-time IMAP IDLE watcher | ✅ | ❌ |
| AI triage with presets | ✅ | ❌ |
| Desktop & webhook alerts | ✅ | ❌ |
| Calendar (ICS) extraction | ✅ | ❌ |
| Email analytics | ✅ | ❌ |
| OAuth2 (Gmail / M365) | ✅ experimental | ❌ |
| Guided setup wizard | ✅ auto-detect | ❌ |
Most MCP email implementations provide only basic read/send. This server aims to be a full-featured email client for AI assistants, covering the entire lifecycle: reading, composing, managing, scheduling, and analyzing email — all from a single MCP server.
Key design decisions:
~/.config/email-mcp/config.tomlRequires Node.js ≥ 22.
No Node.js required — just Docker.
Tag convention: Tags follow bare semver (no
vprefix), matching Docker ecosystem standards (e.g.node:24,nginx:1.25). Thelatesttag is only updated on stable releases, never pre-releases.
Note: The server uses stdio transport. Config must be created on the host first (via
npx @codefuturist/email-mcp setupor manually) and mounted into the container.
The setup wizard auto-detects server settings, tests connections, saves config, and outputs the MCP client config snippet.
Recommended — use the guided installer (auto-detects Claude Desktop, VS Code, Cursor, Windsurf):
Or add manually using the snippets below.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Option 1 — Extensions gallery (easiest):
@mcp email-mcpOption 2 — Workspace config (.vscode/mcp.json, committed to source control):
Option 3 — User config (settings.json, applies to all workspaces):
Open the Command Palette → Preferences: Open User Settings (JSON) and add:
Edit ~/.cursor/mcp.json:
Edit ~/.codeium/windsurf/mcp_config.json:
Edit ~/.config/zed/settings.json:
Add to ~/.vibe/config.toml:
To pass credentials directly instead of using a config file, use the env field:
MCP tools are exposed as email-mcp_<tool_name> (e.g. email-mcp_list_emails). Restart Vibe after editing the config.
Run the server in a container — mount your config directory read-only:
For MCP client configuration (e.g. Claude Desktop):
Located at $XDG_CONFIG_HOME/email-mcp/config.toml (default: ~/.config/email-mcp/config.toml).
Note: OAuth2 support is experimental. Token refresh and provider-specific flows may require additional testing in your environment.
For single-account setups (overrides config file):
| Variable | Default | Description |
|---|---|---|
MCP_EMAIL_ADDRESS | required | Email address |
MCP_EMAIL_PASSWORD | required | Password or app password |
MCP_EMAIL_IMAP_HOST | required | IMAP server hostname |
MCP_EMAIL_SMTP_HOST | required | SMTP server hostname |
MCP_EMAIL_ACCOUNT_NAME | default | Account name |
MCP_EMAIL_FULL_NAME | — | Display name |
MCP_EMAIL_USERNAME | Login username | |
MCP_EMAIL_IMAP_PORT | 993 | IMAP port |
MCP_EMAIL_IMAP_TLS | true | IMAP TLS |
MCP_EMAIL_SMTP_PORT | 465 | SMTP port |
MCP_EMAIL_SMTP_TLS | true | SMTP TLS |
MCP_EMAIL_SMTP_STARTTLS | false | SMTP STARTTLS |
MCP_EMAIL_SMTP_VERIFY_SSL | true | Verify SSL certificates |
MCP_EMAIL_SMTP_POOL_ENABLED | true | Enable SMTP transport pooling |
MCP_EMAIL_SMTP_POOL_MAX_CONNECTIONS | 1 | Max pooled SMTP connections |
MCP_EMAIL_SMTP_POOL_MAX_MESSAGES | 100 | Max messages per pooled connection |
MCP_EMAIL_RATE_LIMIT | 10 | Max sends per minute |
The scheduler enables future email delivery with a layered architecture:
email-mcp scheduler check for manual or cron-based processingemail-mcp scheduler install sets up launchd (macOS) or crontab (Linux) to run every minute, independently of the MCP serverImportant — the daemon must be installed for reliable delivery. Without it, scheduled emails only fire while an AI client is actively connected. Your machine also needs to be running at the scheduled time; if it's asleep or off, the daemon will process overdue emails on next wake/startup. Failed sends are retried up to 3 times before being marked
failed.
Scheduled emails are stored as JSON files in ~/.local/state/email-mcp/scheduled/ with status-based locking. Each entry tracks attempts (max 3) and the last error, so you can inspect failures with scheduler list.
The IMAP IDLE watcher monitors configured mailboxes in real-time using persistent IDLE connections (separate from tool connections). When new emails arrive:
Configure in config.toml:
| Preset | Focus | Suggested Labels |
|---|---|---|
inbox-zero | Aggressive categorization + archiving | Newsletter, Notification, Updates, Finance, Social, Promo |
gtd | Getting Things Done contexts | @Action, @Waiting, @Reference, @Someday, @Delegated |
priority-focus | Simple priority classification (default) | (none — just priority + flag) |
notification-only | No AI triage, just log | (none) |
custom | User defines full system prompt | User-defined |
Static rules use glob-style patterns (*@github.com) with | as OR separator (*@github.com|*@gitlab.com). All conditions within a match are AND'd. First matching rule wins.
Available actions: labels (string array), flag (boolean), mark_read (boolean), alert (boolean — forces desktop notification).
Urgency-based multi-channel notification routing — grab attention for important emails even when you're not looking at the chat. All channels are opt-in and disabled by default.
| Priority | Desktop | Sound | MCP Log Level | Webhook |
|---|---|---|---|---|
urgent | ✅ Banner | 🔊 Alert | alert | ✅ |
high | ✅ Banner | 🔇 Silent | warning | ✅ |
normal | ❌ | ❌ | info | ❌ |
low | ❌ | ❌ | debug | ❌ |
Supported platforms: macOS (Notification Center via osascript), Linux (notify-send), Windows (PowerShell toast). Zero npm dependencies — uses native OS commands.
Notification setup by platform:
Desktop notifications use osascript (built-in). The terminal app running the MCP server needs notification permission:
Use check_notification_setup to diagnose and test_notification to verify.
Requires notify-send from libnotify. For sound alerts, paplay is also needed:
Desktop notifications require a running display server (X11/Wayland) — they will not work in headless/SSH sessions.
Uses PowerShell toast notifications (built-in):
AI-configurable: The AI can check, test, and configure notifications at runtime:
check_notification_setup — diagnose platform support and show setup instructionstest_notification — send a test notification to verify everything worksconfigure_alerts — enable/disable desktop, sound, threshold, webhook (with optional persist to config file)Webhook payload:
Static rules can force desktop notifications with alert = true, regardless of urgency threshold:
Features:
notifications/resources/updated for unread counts| Tool | Description |
|---|---|
list_accounts | List all configured email accounts |
list_mailboxes | List folders with unread counts and special-use flags |
list_emails | Paginated email listing with date, sender, subject, and flag filters |
get_email | Read full email content with attachment metadata |
get_emails | Fetch full content of multiple emails in a single call (max 20) |
get_email_status | Get read/flag/label state of an email without fetching the body |
search_emails | Search by keyword across subject, sender, and body |
download_attachment | Download an email attachment by filename |
find_email_folder | Discover the real folder(s) an email resides in (resolves virtual folders) |
extract_contacts | Extract unique contacts from recent email headers |
get_thread | Reconstruct a conversation thread via References/In-Reply-To |
list_templates | List available email templates |
get_email_stats | Email analytics — volume, top senders, daily trends |
check_health | Connection health, latency, quota, and IMAP capabilities |
| Tool | Description |
|---|---|
send_email | Send a new email (plain text or HTML, CC/BCC) |
reply_email | Reply with proper threading (In-Reply-To, References) |
forward_email | Forward with original content quoted |
save_draft | Save an email draft to the Drafts folder |
send_draft | Send an existing draft and remove from Drafts |
apply_template | Apply a template with variable substitution |
schedule_email | Schedule an email for future delivery |
list_scheduled | List scheduled emails by status |
cancel_scheduled | Cancel a pending scheduled email |
| Tool | Description |
|---|---|
move_email | Move email between folders |
delete_email | Move to Trash or permanently delete |
mark_email | Mark as read/unread, flag/unflag |
bulk_action | Batch operation on up to 100 emails |
create_mailbox | Create a new mailbox folder |
rename_mailbox | Rename an existing mailbox folder |
delete_mailbox | Permanently delete a mailbox and contents |
| Tool | Description |
|---|---|
list_labels | Discover available labels (auto-detects provider strategy) |
add_label | Add a label to an email (ProtonMail folders, Gmail X-GM-LABELS, or IMAP keywords) |
remove_label | Remove a label from an email |
create_label | Create a new label |
delete_label | Delete a label |
| Tool | Description |
|---|---|
get_watcher_status | Show IMAP IDLE connections, folders being monitored, and last-seen UIDs |
list_presets | List available AI triage presets with descriptions and suggested labels |
get_hooks_config | Show current hooks configuration — preset, rules, and custom instructions |
configure_alerts | Update alert/notification settings at runtime |
check_notification_setup | Diagnose desktop notification support and provide setup instructions |
test_notification | Send a test notification to verify OS permissions are configured |
| Tool | Description |
|---|---|
extract_calendar | Extract ICS/iCalendar events from an email |
analyze_email_for_scheduling | Analyze an email to detect events and reminder-worthy content |
add_to_calendar | Add an email event to the local calendar (macOS/Linux) |
create_reminder | Create a reminder in macOS Reminders.app from an email |
list_calendars | List all available local calendars |
check_calendar_permissions | Check whether the local calendar is accessible |
| Prompt | Description |
|---|---|
triage_inbox | Categorize and prioritize unread emails with suggested actions |
summarize_thread | Summarize an email conversation thread |
compose_reply | Draft a context-aware reply to an email |
draft_from_context | Compose a new email from provided context and instructions |
extract_action_items | Extract actionable tasks from email threads |
summarize_meetings | Summarize upcoming calendar events from emails |
cleanup_inbox | Suggest emails to archive, delete, or unsubscribe from |
| Resource | URI | Description |
|---|---|---|
| Accounts | email://accounts | List of configured accounts |
| Mailboxes | email://{account}/mailboxes | Folder tree for an account |
| Unread | email://{account}/unread | Unread email summary |
| Templates | email://templates | Available email templates |
| Stats | email://{account}/stats | Email statistics snapshot |
| Scheduled | email://scheduled | Pending scheduled emails |
| Provider | Domains |
|---|---|
| Gmail | gmail.com |
| Outlook / Hotmail | outlook.com, hotmail.com, live.com |
| Yahoo Mail | yahoo.com, ymail.com |
| iCloud | icloud.com, me.com, mac.com |
| Fastmail | fastmail.com |
| ProtonMail Bridge | proton.me, protonmail.com |
| Zoho Mail | zoho.com |
| GMX | gmx.com, gmx.de, gmx.net |
PRs accepted. Please conform to the standard-readme specification when editing this README.