Email MCP

What codefuturist/email-mcp MCP server does

The codefuturist/email-mcp MCP server exposes email operations over Model Context Protocol for accounts that support IMAP and SMTP. It can inspect folders and unread counts, list or search messages, retrieve full message content, inspect status flags, download attachments, reconstruct threads, and extract contacts from recent headers.

The server also covers outbound and organizational workflows. Agents can send new messages, reply with threading headers, forward existing content, save and send drafts, apply templates, schedule future delivery, and cancel scheduled messages. Mail can be moved, deleted, marked read or unread, flagged, or processed in bulk. Mailbox creation, renaming, and deletion are also available.

How it works

Connections use IMAP for mailbox access and SMTP for sending. Multiple accounts can be configured and operated through the same MCP server. Provider settings can be detected for services including Gmail, Outlook, Yahoo, iCloud, Fastmail, ProtonMail, Zoho, GMX, and ProtonMail as listed by the project.

The server uses stdio transport. It stores its default configuration in the XDG-style path ~/.config/email-mcp/config.toml, while a single account can alternatively be supplied through environment variables. A setup wizard can detect server settings, test connections, save configuration, and produce an MCP client configuration snippet.

Additional functions include message statistics, connection health checks, scheduled-message management, template variable substitution, and provider-aware label handling. The README also describes an IMAP IDLE watcher, AI triage with presets and rules, desktop or webhook alerts, and calendar extraction from ICS content.

Setup and configuration

The codefuturist/email-mcp MCP server requires Node.js 22 or newer when run with its npm package. The directly runnable MCP configuration is:

{
  "command": "npx",
  "args": ["-y", "@codefuturist/email-mcp", "stdio"]
}

Before starting the MCP process, create an account configuration with npx @codefuturist/email-mcp setup, or use the CLI commands email-mcp account add and email-mcp config init. The setup flow is recommended for interactive account creation and connection testing. Docker is also supported; the host configuration directory must be mounted into the container because the transport remains stdio.

For a single account without a configuration file, the documented variables are MCP_EMAIL_ADDRESS, MCP_EMAIL_PASSWORD, MCP_EMAIL_IMAP_HOST, and MCP_EMAIL_SMTP_HOST. Gmail and Microsoft 365 OAuth2 authentication is described as experimental.

Tools and capabilities

The exposed operations include:

• Browse mailboxes and paginated messages with sender, date, subject, and flag filters.
• Read one or multiple messages, inspect status, search content, resolve folders, and reconstruct threads.
• Send, reply to, forward, draft, template, schedule, cancel, and bulk-process email.
• Download attachments, with downloads capped at 5 MB and returned as base64.
• Create, rename, delete, and move through mailbox folders.
• Extract contacts and produce email volume, sender, and daily-trend statistics.
• Check connection health, latency, quota, and IMAP capabilities.

Limitations and notes

The codefuturist/email-mcp MCP server requires valid email account access and does not replace the provider’s IMAP or SMTP permissions. OAuth2 support is experimental rather than documented as the default authentication path. Attachments larger than 5 MB cannot be downloaded through the documented attachment operation.

Connections use TLS or STARTTLS, passwords are not logged, and an audit trail records operations without credentials. A configurable token-bucket rate limiter applies per account. Configuration should be created on the host before using the Docker image, and the mounted configuration directory is shown as read-only in the example.