SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsemail-mcp

email-mcp

IMAP/SMTP email across multiple accounts: read, search, send, schedule and manage mail, with IMAP IDLE push, AI triage and desktop notifications.

Open website

About this tool

email-mcp is an MCP (Model Context Protocol) server that provides AI assistants with comprehensive email capabilities through IMAP and SMTP, enabling them to read, search, send, manage, schedule, and analyze email across multiple accounts. The project is positioned to become a full-featured email client for AI assistants, covering the complete email lifecycle: reading, composing, managing, scheduling, and analyzing, rather than just basic reading and sending.

Main capabilities

  • Exposes 47 tools, 7 prompts, and 6 resources through the MCP protocol.
  • Multi-account support: can operate multiple IMAP/SMTP accounts simultaneously.
  • Supports OAuth2 XOAUTH2 authentication (Gmail and Microsoft 365, experimental).
  • Email scheduling: supports future-time delivery, with a layered architecture (MCP auto-check, CLI, OS-level daemon).
  • Calendar extraction, analysis, and provider-aware label management.
  • Real-time IMAP IDLE listener, combined with AI triage, customizable presets, and static rules.
  • Guided setup wizard that automatically detects server settings, tests the connection, saves the configuration, and outputs MCP client configuration snippets.
  • Automatic provider detection: Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX.

Security and design

  • All connections use TLS/STARTTLS encryption.
  • Passwords are never logged; the audit trail records operations but contains no credentials.
  • Token bucket rate limiter prevents abuse (configurable per account).
  • Attachment download is limited to 5 MB, using base64 encoding.
  • Configuration follows the XDG specification, with the TOML file located at ~/.config/email-mcp/config.toml.
  • Layered services: business logic is decoupled from MCP wiring for easier testing.

Usage

  • Requires Node.js ≥ 22; Docker can also be used, with no need for Node.js.
  • The server uses stdio transport. Configuration must first be created on the host (via npx @codefuturist/email-mcp setup or manually), then mounted into the container.
  • Provides a guided installer that can automatically detect Claude Desktop, VS Code, Cursor, and Windsurf.
  • Supports manual configuration of multiple MCP clients, including Claude Desktop, VS Code (Extension Gallery, workspace configuration, user configuration), Cursor, Windsurf, Zed, Vibe.
  • Credentials can be passed directly via the env field instead of using a configuration file.
  • MCP tools are exposed as email-mcp_<tool_name> (for example, email-mcp_list_emails). Vibe must be restarted after editing the configuration.
  • Docker run: mount the configuration directory as read-only.
  • Single-account settings can override the configuration file.

Scheduled email sending

  • MCP automatic check: the server processes the queue at startup and every 60 seconds during operation.
  • CLI: email-mcp scheduler check for manual or cron-based processing.
  • OS-level daemon: email-mcp scheduler install sets up launchd (macOS) or crontab (Linux), runs every minute, independent of the MCP server.
  • Important: the daemon must be installed for reliable delivery. Otherwise, scheduled emails are only triggered when the AI client actively connects. The machine must be running at the scheduled time; if it is asleep or shut down, the daemon will process overdue emails on the next wake/startup. Failed sends are retried up to 3 times, after which they are marked as failed.
  • Scheduled emails are stored as JSON files in ~/.local/state/email-mcp/scheduled/, with status locking. Each record tracks the number of attempts (up to 3) and the last error; failures can be checked with scheduler list.

Real-time listening and AI hooks

  • The IMAP IDLE listener uses a persistent IDLE connection (independent of tool connections) to monitor configured mailboxes in real time.
  • When new mail arrives: static rules match by from/to/subject patterns and immediately apply labels, flags, or mark as read (no AI required); remaining emails undergo AI triage via MCP sampling using customizable preset prompts; if AI triage is disabled, it falls back to logging (notify mode).
  • Static rules use glob-style patterns (@github.com), with | as the OR separator (@github.com|*@gitlab.com). All conditions within a match are AND. The first matching rule takes effect.
  • Available actions: labels (string array), flag (boolean), mark_read (boolean), alert (boolean — forces a desktop notification).
  • Multi-channel notification routing based on urgency level: all channels are off by default and must be actively enabled.
  • Supported platforms: macOS (via osascript's Notification Center), Linux (notify-send), Windows (PowerShell toast). Zero npm dependencies, using native operating system commands.
  • Desktop notification settings vary by platform: macOS requires granting notification permission to the terminal application running the MCP server; Linux requires libnotify's notify-send, and sound alerts also require paplay, plus a running display server (X11/Wayland); headless/SSH sessions are unavailable; Windows uses built-in PowerShell toast notifications.
  • AI can inspect, test, and configure notifications at runtime: check_notification_setup, test_notification, configure_alerts (can optionally persist to a configuration file).
  • Static rules can force desktop notifications via alert = true, unaffected by urgency thresholds.
  • Other features: exponential backoff auto-reconnect on connection failure (1s → 60s); batching groups arriving emails by a configurable delay to reduce AI calls; rate limiting to at most 10 sampling calls per minute; graceful degradation — if the client does not support sampling, fall back to notify mode; resource subscription — push notifications/resources/updated to update the unread count.

Use cases

  • Users who want to let an AI assistant directly manage multiple email accounts.
  • Scenarios requiring scheduled email sending, real-time monitoring with AI triage, and desktop notification reminders.
  • Developers using MCP clients such as Claude Desktop, VS Code, Cursor, Windsurf, Zed, and Vibe.

Limitations

  • OAuth2 support is experimental; token refresh and provider-specific flows may require additional testing in your environment.
  • Reliable delivery of scheduled emails dependson an operating system-level daemon, and the machine must be running at the scheduled time.
  • Attachment download limit is 5 MB.
  • Linux desktop notifications require a display server; headless/SSH sessions are unavailable.
  • Requires Node.js ≥ 22 (or use Docker).
  • License is LGPL-3.0-or-later.

Related tools

Browse category